Skip to content

Deploy MagicSync with Coolify ​

This guide explains how to deploy MagicSync on your own server using Coolify, an open-source platform for self-hosting applications.

Why Coolify?

  • Simple deployment — Manage containers through a web UI.
  • Self-hosted — Keep control of your own infrastructure.
  • Cost effective — Use affordable VPS providers.
  • Automatic SSL — Free HTTPS certificates via Let's Encrypt.
  • Git-based updates — Redeploy automatically on push.

Prerequisites ​

Before you start, you will need:

RequirementPurposeExamples
VPS or serverHost the applicationHetzner, DigitalOcean, Linode, Vultr
DockerContainer runtimeInstalled by Coolify automatically
CoolifyDeployment platformcoolify.io
GitHub accountSource repositorygithub.com
  • CPU: 2+ cores
  • RAM: 4GB+ (8GB recommended for production)
  • Storage: 40GB+ SSD
  • OS: Ubuntu 22.04 LTS

Architecture Overview ​

The Coolify deployment consists of three services:

┌─────────────────────────────────────────┐
│              VPS Server                 │
│  ┌─────────────────────────────────┐   │
│  │            Coolify              │   │
│  │  ┌─────────────────────────┐   │   │
│  │  │   MagicSync Site        │   │   │
│  │  │   ghcr.io/leamsigc/     │   │   │
│  │  │   magicsync:latest      │   │   │
│  │  └─────────────────────────┘   │   │
│  │  ┌─────────────────────────┐   │   │
│  │  │   Python Backend        │   │   │
│  │  │   (built from source)   │   │   │
│  │  └─────────────────────────┘   │   │
│  │  ┌─────────────────────────┐   │   │
│  │  │   Database (libSQL)     │   │   │
│  │  └─────────────────────────┘   │   │
│  └─────────────────────────────────┘   │
└─────────────────────────────────────────┘
              │
              ▼
    https://magicsync.dev:8888
  • Site — Pre-built Nuxt image from ghcr.io/leamsigc/magicsync.
  • Python Backend — Built from the repository source.
  • Database — Official libSQL server image.

Step 1: Install Coolify ​

1.1 Prepare Your Server ​

Provision a VPS with Ubuntu 22.04 and point your domain to the server's IP address.

This guide uses the example domain:

https://magicsync.dev:8888

You can replace it with your own domain and port.

1.2 Install Coolify ​

SSH into your server and run the install script:

bash
curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash

This installs Docker and Coolify. After installation, Coolify will provide a URL such as:

http://your-server-ip:8000

Open it in your browser and create your admin account.


Step 2: Connect Your GitHub Repository ​

  1. In Coolify, go to Sources.
  2. Click Add GitHub App.
  3. Follow the steps to connect your GitHub account.
  4. Select the leamsigc/magicsync repository.

Step 3: Create a Docker Compose Resource ​

  1. Go to Projects and select or create a project.
  2. Click Add New Resource.
  3. Choose Docker Compose.
  4. Select the leamsigc/magicsync repository.

Use the Pre-Built Image ​

Replace the contents of the Docker Compose file in Coolify with the following:

yaml
services:
  site:
    image: ghcr.io/leamsigc/magicsync:v1.0.0  # Replace with the latest release tag
    depends_on:
      - db
    environment:
      - NUXT_HOST=0.0.0.0
    volumes:
      - uploads:/usr/app/upload/files

  # Optional: Python-only tools sidecar. Remove if you do not need it.
  python-tools:
    build:
      context: ./packages/python-tools
      dockerfile: Dockerfile
    environment:
      - PYTHON_TOOLS_TOKEN=<optional-bearer-token>

  db:
    image: ghcr.io/tursodatabase/libsql-server:latest
    platform: linux/amd64
    volumes:
      - db-data:/var/lib/sqld

volumes:
  db-data:
  uploads:

Important notes about the image:

  • Pin the tag: The example uses v1.0.0. Replace this with the actual tag you want to deploy. Check the GitHub releases page for available tags. Pinning a tag makes deployments reproducible.
  • Avoid latest in production: Using latest can lead to unexpected updates. Always use a specific tag for production deployments.
  • Private registry: If the image is private, add your GitHub Container Registry credentials in Coolify under Settings → Private Registries.
  • Cache: Docker may cache latest. To force a fresh pull, redeploy or use a specific tag.

What this does:

  • The site uses the pre-built image, so no build is required. Chat, agents, the content board, RAG, and video ingestion all run inside this container.
  • The python-tools sidecar is optional and only needed for Python-only tools; point AI settings → Tool backends at http://python-tools:8100.
  • The db uses the official libSQL server image.
  • Named volumes persist the database and uploads across restarts.

Step 4: Set Environment Variables ​

In Coolify, open the Environment Variables tab for your resource. You can paste the contents of .env-example directly — Coolify understands .env format.

Important: .env-example is written for local development. For Coolify, you must change localhost values to Docker service names and your real domain.

Required Environment Variables ​

bash
# ============================================================
# APP CONFIGURATION
# ============================================================
NUXT_HOST=0.0.0.0
NUXT_APP_URL=https://magicsync.dev:8888
NUXT_BASE_URL=https://magicsync.dev:8888
NUXT_SESSION_PASSWORD=<generate-with-openssl-rand-hex-32>

# ============================================================
# BETTER AUTH
# ============================================================
NUXT_BETTER_AUTH_URL=https://magicsync.dev:8888
NUXT_BETTER_AUTH_SECRET=<generate-with-openssl-rand-hex-32>
BETTER_AUTH_URL=https://magicsync.dev:8888
BETTER_AUTH_SECRET=<generate-openssl-rand-hex-32>

# ============================================================
# DATABASE (libSQL via Docker)
# ============================================================
JWT=<generate-with-openssl-rand-hex-32>
SQLD_AUTH_JWT_KEY=<generate-with-openssl-rand-hex-32>
NUXT_TURSO_DATABASE_URL=http://db:8080
NUXT_TURSO_AUTH_TOKEN=<same-as-JWT>

# ============================================================
# AGENT RUNTIME (in-process pi SDK)
# ============================================================
MACHINE_BRIDGE_SECRET=<generate-with-openssl-rand-hex-32>
NUXT_PUBLISH_SECRET=<generate-with-openssl-rand-hex-32>

# ============================================================
# TOOL BACKENDS (optional)
# ============================================================
# Deployment fallbacks; users can set their own in AI settings.
SGAI_API_KEY=<your-scrapegraphai-api-key>
PYTHON_TOOLS_URL=http://python-tools:8100
PYTHON_TOOLS_TOKEN=<optional-bearer-token>

# ============================================================
# OLLAMA (optional — for local AI)
# ============================================================
# Agents use pi ModelRuntime; select Ollama in AI settings with base URL
# http://ollama:11434/v1. Otherwise use cloud provider keys below.

# ============================================================
# FILE STORAGE
# ============================================================
NUXT_FILE_STORAGE_MOUNT=./upload/files

# ============================================================
# EMAIL (Mailgun)
# ============================================================
NUXT_MAILGUN_API_KEY=<your-mailgun-api-key>
NUXT_MAILGUN_DOMAIN=<your-mailgun-domain>
NUXT_MAIL_FROM_EMAIL=noreply@magicsync.dev

# ============================================================
# AI SERVICES
# ============================================================
NUXT_OPENAI_API_KEY=<your-openai-api-key>
NUXT_PEXELS_API_KEY=<your-pexels-api-key>
NUXT_GOOGLE_GENERATIVE_AI_API_KEY=<your-google-api-key>

# ============================================================
# SOCIAL MEDIA OAUTH KEYS
# ============================================================
# Add the platforms you want to use.
# See /guide/platform-keys for each platform's setup.

Generate Secret Keys ​

Run the following on your local machine or server:

bash
openssl rand -hex 32  # JWT
openssl rand -hex 32  # SQLD_AUTH_JWT_KEY
openssl rand -hex 32  # NUXT_SESSION_PASSWORD
openssl rand -hex 32  # NUXT_BETTER_AUTH_SECRET
openssl rand -hex 32  # BETTER_AUTH_SECRET
openssl rand -hex 32  # NUXT_PUBLISH_SECRET
openssl rand -hex 32  # MACHINE_BRIDGE_SECRET

Important: JWT and NUXT_TURSO_AUTH_TOKEN must be the same value.

Changes from .env-example ​

In .env-exampleIn CoolifyReason
NUXT_TURSO_DATABASE_URL=http://localhost:8080http://db:8080Docker services communicate by name
PYTHON_TOOLS_URL=http://localhost:8100http://python-tools:8100Docker services communicate by name (only if you run the optional sidecar)
NUXT_APP_URL=http://localhost:3000https://magicsync.dev:8888Your public domain

Step 5: Configure the Domain ​

Set Your Domain ​

In Coolify, go to your resource settings and set:

Domain: https://magicsync.dev:8888

You can also use a subdomain such as https://app.magicsync.dev.

Enable HTTPS ​

Coolify can automatically provision a free SSL certificate from Let's Encrypt:

  1. Go to Settings → SSL/TLS.
  2. Turn on Let's Encrypt.
  3. Click Save.

Step 6: Deploy ​

  1. Review all settings.
  2. Click Deploy.
  3. Wait for the deployment to complete (this may take a few minutes).
  4. Check the logs for any errors.

Once finished, open your browser and visit:

https://magicsync.dev:8888

MagicSync Home


Updating Your Deployment ​

Automatic Updates ​

  1. In Coolify, go to your resource.
  2. Find the Webhooks or Auto Deploy settings.
  3. Enable auto-deploy on push.

Manual Updates ​

  1. Go to your resource in Coolify.
  2. Click Pull Latest Image or Redeploy.

Security Best Practices ​

  • Use HTTPS with Let's Encrypt.
  • Store all secrets in Coolify environment variables, never in your code.
  • Use strong, randomly generated secrets.
  • Enable 2FA on your Coolify account.
  • Keep Coolify and your server updated.
  • Back up your database regularly.

Troubleshooting ​

Site will not load ​

  1. Check that the deployment finished successfully.
  2. Verify the domain points to your server: ping magicsync.dev
  3. Check that the containers are running in the Coolify dashboard.
  4. Ensure the required port is open if using a custom port.

Environment variables not working ​

  1. Verify the variables are saved in Coolify.
  2. Redeploy after changing environment variables.
  3. Check for typos in variable names.

Database connection failed ​

  1. Check that the database container is running.
  2. Verify JWT matches NUXT_TURSO_AUTH_TOKEN.
  3. Verify SQLD_AUTH_JWT_KEY is set.
  4. Make sure NUXT_TURSO_DATABASE_URL is http://db:8080, not localhost.

Python tools sidecar cannot connect ​

  1. Verify PYTHON_TOOLS_URL is http://python-tools:8100 (or the URL set in AI settings).
  2. Check that the python-tools container is running.
  3. Use the Test button in AI settings → Tool backends; it probes /health.

Agents fail with MODEL_NOT_CONFIGURED ​

Set a provider/model in Account → AI settings (global) or a per-business override; AGENT_DEFAULT_PROVIDER / AGENT_DEFAULT_MODEL are deployment fallbacks. ScrapeGraphAI errors (SCRAPEGRAPH_NOT_CONFIGURED) are fixed by adding a key in AI settings → Tool backends or setting SGAI_API_KEY.

SSL certificate will not generate ​

  1. Verify the domain points to your server.
  2. Make sure port 80 is open (required by Let's Encrypt).
  3. Try regenerating the certificate in Coolify.

Next Steps ​

Released under the MIT License.