Skip to main content

Synkronus Quickstart — Deploy in Minutes

Get a full Synkronus server running in minutes with Docker or Podman, including database, automated HTTPS, and portal UI.

TL;DR: Clone, run installer, done. See Easiest: Run the Installer.

What you get

  • ✅ Synkronus server — REST API for mobile app sync
  • ✅ PostgreSQL database — Data persistence
  • ✅ Synkronus Portal — Web UI for admin tasks
  • ✅ Caddy reverse proxy — Auto TLS/HTTPS (Let's Encrypt)
  • ✅ Single Docker volume — All data in one place
  • ✅ Works locally or in cloud — GitHub Codespaces ready

Prerequisites

Docker or Podman

# macOS (Homebrew)
brew install podman podman-compose

# Ubuntu/Debian
sudo apt update && sudo apt install -y podman podman-compose git

Git — Clone the repository

Easiest: Run the Installer ⭐

The installer generates strong passwords, configures TLS, and handles everything.

# 1. Clone the repository
git clone --depth 1 https://github.com/OpenDataEnsemble/synkronus-quickstart.git server
cd server

# 2. Run the installer
chmod +x ./install.sh
./install.sh

# 3. Start the stack
podman compose up -d

The installer will ask:

Do you have a domain name?

  • Yes → Enter your domain (e.g., myserver.com)

    • Caddy obtains a real TLS certificate from Let's Encrypt
    • Access: https://myserver.com

  • No, use public IP → Enter your server's IP

    • Caddy uses <ip>.sslip.io (real certificate)
    • Access: https://<ip>.sslip.io

  • No, localhost → Local testing only

    • HTTP on localhost:80
    • Access: http://localhost

Output:

Admin username: admin
Admin password: < strong password saved >

Save these credentials!

After setup

Access the portal

  • Domain: https://myserver.com
  • Public IP: https://<your-ip>.sslip.io
  • Localhost: http://localhost

Login with the credentials from the installer.

Create users

In Synkronus Portal:

  1. Settings → Users
  2. Click + Add User
  3. Enter username, password, and permissions

Verify the server

# Check if server is running
curl https://myserver.com/health
# Response: "OK"

Data storage

Data is stored in a single Docker volume at /app/data:

/app/data/
├── app-bundle/active/      # Currently deployed app bundle
├── app-bundle/versions/     # Version history
├── attachments/             # Photos, documents, etc.
└── database/                # PostgreSQL data (in named volume)

To find the volume path:

podman volume inspect <volume_name> --format '{{ .Mountpoint }}'

Utilities

The repo includes helpful scripts:

ScriptPurpose
backup-db.shBackup PostgreSQL database to .sql file
backup-attachments.shCopy attachment blobs from container
migrate-synkronus-data.shUsed when upgrading from older versions

Example: Backup the database

chmod +x ./utilities/backup-db.sh
./utilities/backup-db.sh
# Creates: synkronus-db-backup-<timestamp>.sql

Manual setup (advanced)

If you prefer to configure manually:

1. Clone and prepare

git clone https://github.com/OpenDataEnsemble/synkronus-quickstart.git
cd synkronus-quickstart

2. Edit docker-compose.yml

Set environment variables:

postgres:
  environment:
    POSTGRES_PASSWORD: <generate strong password>

synkronus:
  environment:
    DB_CONNECTION: "user=synkronus password=<from postgres> host=db dbname=synkronus"
    JWT_SECRET: <openssl rand -base64 32>
    ADMIN_USERNAME: admin
    ADMIN_PASSWORD: <strong password>

3. Initialize the database

# Terminal 1: Start database only
podman compose up db

# Terminal 2: Create the Synkronus database
chmod +x ./create_sync_db.sh
./create_sync_db.sh

4. Start the full stack

podman compose up -d

5. Verify

curl http://localhost:8080/health
# Response: "OK"

Using GitHub Codespaces

Perfect for trying out Synkronus in 30 seconds — no local setup needed.

  1. Go to synkronus-quickstart repo
  2. Click "Open in Codespaces"
  3. Wait for startup (containers will auto-start)
  4. Check Ports tab to find the forwarded URL
  5. Test: 
    curl <forwarded-url>/health

Upgrading from older versions

If you previously used older paths for app bundles:

  1. Stop the stack:

    podman compose down

  2. Backup the data volume:

    docker run --rm \
  -v <your_appdata_volume>:/data \
  -v "$(pwd)":/backup alpine \
  tar czf /backup/backup.tgz -C /data .

  3. Run the migration script:

    chmod +x ./utilities/migrate-synkronus-data.sh
podman run --rm \
  -v <volume_name>:/data:Z \
  -v "$PWD/utilities/migrate-synkronus-data.sh:/migrate.sh:ro,Z" \
  docker.io/library/alpine:3.21 \
  sh /migrate.sh /data

  4. Start the new version:

    podman compose up -d

See upgrade-path.md for full details.

Troubleshooting

ProblemSolution
Certificate error on first bootWait 1-2 minutes for Let's Encrypt validation. Restart Caddy: podman restart synkronus_caddy
Can't connect to serverVerify stack is running: podman compose ps
Database won't startCheck disk space and container logs: podman logs db
Lost attachmentsUse backup-attachments.sh before recreating containers

Next steps

  1. Build a custom app — Create your first data collection app
  2. Install Formulus — Get the mobile app
  3. Configure mobile nodes — Set up offline sync
  4. Join the community — forum.opendataensemble.org

Reference

Ready to sync data? 🚀