Getting Started with Synapse Go

This guide will help you get up and running with the Synapse Go project on your local machine. We'll cover the prerequisites, installation, build process, and basic usage.

Prerequisites

Before you begin, ensure you have the following installed:

• Go 1.23.8+ (The project uses Go 1.23.8 with toolchain 1.24.1)
• Make (for building and packaging)
• Git (for cloning the repository)
• Unzip (for extracting the packaged application)

You can check your Go version with:

go version

If you need to install or update Go, visit the official Go download page.

Cloning the Repository

1. Clone the repository using Git:

git clone https://github.com/apache/synapse-go.git

2. Navigate to the project directory:

cd synapse-go

Building the Project

The project includes a comprehensive Makefile with several useful targets:

Basic Build Commands

• Build the project (creates the binary in the bin/ directory):

make build

• Build with debug information (useful for development and troubleshooting):

make build-debug

• Run tests:

make test

Packaging the Application

Create a distributable package containing the compiled binary and the required directory structure:

make package

This command:

1. Builds the application
2. Runs tests to ensure everything works
3. Creates a temporary directory structure
4. Packages everything into synapse.zip

All-in-One Command

You can run all steps (dependency resolution, build, and package) with a single command:

make

or

make all

Cleaning Build Artifacts

To clean up all build artifacts:

make clean

Running Synapse Go

After building and packaging, follow these steps to run the application:

1. Extract the package:

unzip synapse.zip

This creates a synapse directory with the following structure:

synapse/
├── bin/
│   └── synapse       # Compiled binary
├── conf/             # Configuration directory
└── artifacts/
    ├── APIs/         # API definitions
    ├── Endpoints/    # Endpoint definitions
    ├── Sequences/    # Sequence definitions
    └── Inbounds/     # Inbound definitions

2. Configure Synapse:

Place your Synapse configuration files in their respective directories:

• Configuration files go into synapse/conf/
• API definitions go into synapse/artifacts/APIs/
• Endpoint definitions go into synapse/artifacts/Endpoints/
• Sequence definitions go into synapse/artifacts/Sequences/
• Inbound definitions go into synapse/artifacts/Inbounds/

Ensure you have a LoggerConfig.toml file in the synapse/conf/ directory to configure logging.

3. Run the application:

cd synapse/bin
./synapse

Configuration Files

Logger Configuration

The logger configuration file (LoggerConfig.toml) should be placed in the synapse/conf/ directory. Here's a basic example:

# Sample LoggerConfig.toml
[logger]
level.default = "warn"

[logger.level.packages]
mediation = "error"
deployers = "error"
router = "info"

[logger.handler]
format = "json"
outputPath = "stdout"

Deployment Configuration

The main configuration file (deployment.toml) should be placed in the synapse/conf/ directory. This file defines the core behavior of your Synapse HTTP server configurations.

Here's a basic example:

[server]
hostname = "localhost"
offset  = 10

Troubleshooting

If you encounter any issues:

1. Ensure your Go version meets the requirements (1.23.8+)
2. Make sure all configuration files are correctly placed in the synapse/conf/ directory
3. Check that the binary has execute permissions:

   chmod +x synapse/bin/synapse
   

4. Check for error messages in the console output

Next Steps

• Review the Architecture Documentation to understand how Synapse works
• Learn about Core Components to customize and extend functionality
• See the Contributing Guidelines if you'd like to contribute to the project

Getting Help

If you need assistance:

• Check the issue tracker for known problems
• Join the community discussions on the mailing list
• Consult the rest of this documentation for detailed information on specific components