Skip to content

Docker Setup ​

MagicSync runs as a single Nuxt container plus a libSQL database. There is no separate backend service — chat, agents, the content board, RAG, and media tooling all run inside the site container. A small Python sidecar is available optionally for Python-only tools.

Prerequisites ​

  • Docker (Engine 24+) with the Compose plugin (docker compose)
  • openssl to generate secrets

Self-Hosting (Pre-built Image) ​

The fastest way to run MagicSync on your own server.

  1. Create a directory for MagicSync

    bash
    mkdir magicsync && cd magicsync
  2. Create docker-compose.yml

    yaml
    services:
      site:
        image: ghcr.io/leamsigc/magicsync:latest
        restart: unless-stopped
        depends_on:
          - db
        env_file:
          - .env
        environment:
          - NUXT_HOST=0.0.0.0
          # Apply pending migrations on first boot (image ships them; see Dockerfile).
          - DB_MIGRATE_ON_BOOT=1
        ports:
          - "3000:3000"
    
      db:
        image: ghcr.io/tursodatabase/libsql-server:latest
        restart: unless-stopped
        platform: linux/amd64
        env_file:
          - .env
        environment:
          - JWT=${JWT}
          - SQLD_AUTH_JWT_KEY=${SQLD_AUTH_JWT_KEY}
        volumes:
          - ./sqld:/var/lib/sqld
        ports:
          - "8080:8080"
  3. Create a .env file

    bash
    # libSQL database (JWT and NUXT_TURSO_AUTH_TOKEN must match)
    JWT=$(openssl rand -hex 32)
    SQLD_AUTH_JWT_KEY=$(openssl rand -hex 32)
    NUXT_TURSO_DATABASE_URL=http://db:8080
    NUXT_TURSO_AUTH_TOKEN=$JWT
    
    # Better Auth
    NUXT_BETTER_AUTH_URL=https://your-domain.com
    NUXT_BETTER_AUTH_SECRET=$(openssl rand -hex 32)
    BETTER_AUTH_SECRET=$NUXT_BETTER_AUTH_SECRET
    NUXT_SESSION_PASSWORD=$(openssl rand -hex 32)
    
    # Credential envelopes + machine routes
    NUXT_PUBLISH_SECRET=$(openssl rand -hex 32)
    MACHINE_BRIDGE_SECRET=$(openssl rand -hex 32)
    
    # Optional: deployment-wide provider / tool fallbacks
    # OPENAI_API_KEY=...
    # SGAI_API_KEY=...            # ScrapeGraphAI default scraper
    # PYTHON_TOOLS_TOKEN=...      # only if you run the python-tools sidecar
  4. Start MagicSync

    bash
    docker compose up -d
  5. Access the application

    • Open http://localhost:3000
    • Create your first account (the first user becomes the admin)

Build From Source ​

The repository ships a docker-compose.yml that builds the site image locally and includes the optional Python sidecar behind a Compose profile.

bash
git clone https://github.com/leamsigc/production-example-nuxt-monorepo.git
cd production-example-nuxt-monorepo
cp .env-example .env   # then fill in the values
docker compose up -d --build

Optional Python tools sidecar (Python-only tools such as ScrapeGraphAI's Python library):

bash
docker compose --profile tools up -d --build
# then set PYTHON_TOOLS_URL=http://python-tools:8100 in .env
# (users can also point at it from AI settings → Tool backends)

What the image contains ​

  • Nuxt server output plus the musl @libsql binding.
  • ffmpeg and the pinned yt-dlp binary (YTDLP_PATH=/usr/local/bin/yt-dlp) for the agent's download_video tool and the video-cropper's GET /api/v1/media/video-download ingest endpoint.
  • Supertonic-3 TTS ONNX assets (downloaded at build time).
  • No Python runtime — the agent runs in-process with the pi SDK. (The pinned yt-dlp is a standalone pyinstaller build, so it does not need one either.)

Reverse proxy timeout: /api/v1/media/video-download resolves the source before it can stream anything, so a request stays open with no response bytes while it works. Worst case is YTDLP_TIMEOUT_MS (120s default) plus, for the few sources that publish no H.264 at all, a YTDLP_TRANSCODE_TIMEOUT_MS (300s default) ffmpeg re-encode. Coolify's Traefik defaults to a 60s read timeout, which would show up as a bare proxy 504 instead of the route's own error — raise the read timeout above the total, or lower both values.

Why videos are re-encoded: sources are requested as H.264 + AAC because some browsers (Firefox on Linux) cannot decode AV1 through WebCodecs and fail later with The given encoding is not supported. Sources that publish no H.264 at all — some Facebook reels are AV1-only — are re-encoded to H.264/AAC server-side, which needs the libx264 and aac encoders in the image. Set YTDLP_BROWSER_SAFE=0 to skip that re-encode.

Scratch folder: downloads are staged in YTDLP_DOWNLOAD_DIR (default /tmp/magicsync-video), which is created on demand. Each download gets its own subfolder that is unlinked once the response settles, so nothing is retained, but peak use is YTDLP_MAX_MB (200MB default) per in-flight request. Mount a real volume at that path rather than relying on the container's overlay /tmp. See .env-example → Video Ingestion.


Development ​

For a hot-reload dev container:

bash
docker compose -f docker-compose.dev.yml up -d

The dev image includes bash, curl, ffmpeg, and the pinned yt-dlp binary. For the Python sidecar in dev, run it on the host with pnpm python-tools:dev and point AI settings at http://localhost:8100.


Environment Variables ​

VariableRequiredDescription
JWT / NUXT_TURSO_AUTH_TOKENYeslibSQL auth token pair — must be the same value
SQLD_AUTH_JWT_KEYYeslibSQL server signing key
NUXT_TURSO_DATABASE_URLYeshttp://db:8080 in Compose (or file:./local.db for dev)
NUXT_BETTER_AUTH_URLYesPublic URL of the site
NUXT_BETTER_AUTH_SECRET / BETTER_AUTH_SECRETYesAuth signing secret — must match
NUXT_SESSION_PASSWORDYesSession encryption (32+ chars)
NUXT_PUBLISH_SECRETYesAES-256-GCM key for credential envelopes and tool-backend secrets
MACHINE_BRIDGE_SECRETYesHMAC secret for GitHub Actions / internal machine routes
OPENAI_API_KEY / NUXT_GOOGLE_GENERATIVE_AI_API_KEYNoServer-side provider keys (users can override per business)
SGAI_API_KEYNoDeployment fallback ScrapeGraphAI key
PYTHON_TOOLS_URL / PYTHON_TOOLS_TOKENNoPython tools sidecar (only with the tools profile)
AGENT_DEFAULT_PROVIDER / AGENT_DEFAULT_MODELNoFallback model when a user has no effective config
DB_MIGRATE_ON_BOOTNo1 applies pending migrations on container boot (fail-fast). Set by docker-compose.yml; DRIZZLE_MIGRATIONS_DIR is baked into the image

See Self-Hosting for the full variable reference, including AGENT_* limits.


Updating, Backups, Logs ​

bash
# Update to the latest image
docker compose pull && docker compose up -d

# Stop / remove containers
docker compose down

# Logs
docker compose logs -f site

# Back up the database files
cp -r sqld backups/sqld-$(date +%Y%m%d)

Troubleshooting ​

SymptomFix
MODEL_NOT_CONFIGURED in chatSet a provider/model in Account → AI settings, or set AGENT_DEFAULT_PROVIDER/AGENT_DEFAULT_MODEL
SCRAPEGRAPH_NOT_CONFIGUREDAdd a ScrapeGraphAI key in AI settings → Tool backends or set SGAI_API_KEY
PYTHON_BACKEND_UNREACHABLEStart the sidecar (docker compose --profile tools up -d) and verify PYTHON_TOOLS_URL
Database connection failedEnsure JWT equals NUXT_TURSO_AUTH_TOKEN and NUXT_TURSO_DATABASE_URL is http://db:8080
Cannot log inCheck NUXT_BETTER_AUTH_SECRET, BETTER_AUTH_SECRET, and NUXT_SESSION_PASSWORD
Container unhealthyCheck docker compose logs site; first boot runs migrations and can take a moment

More Deployment Options ​

Released under the MIT License.