Server Setup

The GoSync server is a single binary for Linux, macOS and Windows. It stores data in SQLite (one server) or PostgreSQL (one or more servers).

Install

Binary: download from GitHub Releases:

bash
curl -L -o gosync.tar.gz https://github.com/HarshalPatel1972/GoSync/releases/latest/download/gosync_Linux_x86_64.tar.gz
tar -xzf gosync.tar.gz
./gosync-server

Builds are available for Linux_x86_64, Linux_arm64, Darwin_x86_64, Darwin_arm64 and Windows_x86_64 (.zip).

Docker: build the image straight from the repository:

bash
docker build -t gosync https://github.com/HarshalPatel1972/GoSync.git#v2.0.0
docker run -p 8080:8080 -e GOSYNC_JWT_SECRET=... -e GOSYNC_DATABASE_URL=postgres://... gosync

Docker Compose with PostgreSQL is in the repository's docker-compose.yml.

Authentication

The server refuses to start without authentication configured. Clients send a token in their first message; the server verifies it and uses one of its claims (by default sub, the user ID) to choose whose data the connection can see.

Identity provider (recommended): point GoSync at your provider's public keys.

bash
export GOSYNC_JWKS_URL=https://YOUR_TENANT.auth0.com/.well-known/jwks.json
export GOSYNC_JWT_ISSUER=https://YOUR_TENANT.auth0.com/
export GOSYNC_JWT_AUDIENCE=https://api.example.com

This works with Auth0, Clerk, Supabase, Firebase, Cognito and any provider that publishes a JWKS. In the browser, getToken returns the user's current token:

javascript
const db = await createClient({ url, getToken: () => auth.currentUser.getIdToken(), dbName });

getToken is called on every reconnect, so expired tokens are refreshed automatically.

Your own backend: sign HS256 tokens with a shared secret of at least 32 bytes.

bash
export GOSYNC_JWT_SECRET=$(openssl rand -hex 32)

Shared team data: set GOSYNC_NAMESPACE_CLAIM to a claim such as org_id, and every user with the same value shares one dataset.

Configuration

All settings are environment variables:

VariableDefaultDescription
GOSYNC_ADDR:8080Listen address
GOSYNC_DATABASE_URLgosync.dbSQLite file path, or a postgres:// URL
GOSYNC_JWKS_URLYour identity provider's JWKS URL
GOSYNC_JWT_SECRETHS256 secret (at least 32 bytes), instead of JWKS
GOSYNC_JWT_ISSUER / GOSYNC_JWT_AUDIENCERequired iss / aud claims
GOSYNC_NAMESPACE_CLAIMsubClaim that selects whose data a connection sees
GOSYNC_ALLOWED_ORIGINSComma-separated browser origins allowed to connect
GOSYNC_TLS_CERT / GOSYNC_TLS_KEYServe wss:// directly (or terminate TLS at a proxy)
GOSYNC_STATIC_DIRAlso serve your web app from this directory
GOSYNC_METRICS_ADDRoffPrivate listener for Prometheus metrics and pprof
GOSYNC_TOMBSTONE_RETENTION720hClean up deleted documents after this long
GOSYNC_DB_MAX_CONNS25PostgreSQL pool size per instance
GOSYNC_LOG_FORMAT / GOSYNC_LOG_LEVELjson / infoLog format and verbosity
GOSYNC_INSECURE_DEV_AUTHtrue trusts any token. Local demos only.

Endpoints: /sync (WebSocket), /healthz (liveness) and /readyz (database reachable).

Commands

bash
gosync-server                           # run the server
gosync-server migrate                   # apply database migrations and exit
gosync-server compact -older-than 720h  # clean up old deleted documents once

Permissions and validation

To enforce rules on the server, such as read-only collections or field validation, embed the server in your own Go program. It's a standard http.Handler:

go
srv, _ := server.New(server.Config{
    Store: store,
    Auth:  auth,
    ValidateMutation: func(ctx context.Context, p server.Principal, m protocol.Mutation) error {
        if m.Collection == "announcements" && !isAdmin(p.Subject) {
            return errors.New("announcements are read-only")
        }
        return nil
    },
})
http.Handle("/sync", srv.Handler())

A rejected write is undone on the device that made it and reported through db.onError.


Next: How conflicts are resolved โ†’