Docker setup¶

Self-host Silex with Docker by building the image from source.

Overview¶

Silex ships a Dockerfile at the repository root. It builds the monorepo (Node.js server, all connectors, and the web editor) into a single image, configured as the full SaaS. You manage the instance through environment variables.

Note: the silexlabs/silex-platform image on Docker Hub is built from this Dockerfile on every release: each version is published with its own tag (e.g. 3.9.0), :latest points to the latest stable release and :canary to the latest prerelease. Building it yourself from source, as shown below, tracks the latest code and avoids depending on a specific registry (a move to a libre registry is being discussed).

Prerequisites¶

Docker installed
Git
Basic understanding of environment variables and port forwarding

Quick start¶

Clone the repository and build the image:

git clone --recurse-submodules https://github.com/silexlabs/Silex.git
cd Silex
docker build -t silex .

Silex stores and publishes sites with GitLab, so first create a GitLab OAuth application. See OAuth app setup. Then run it:

docker run -d --name silex -p 6805:6805 \
  -e SILEX_SESSION_SECRET="$(openssl rand -base64 32)" \
  -e SILEX_URL=http://localhost:6805 \
  -e STORAGE_CONNECTORS=gitlab \
  -e HOSTING_CONNECTORS=gitlab \
  -e GITLAB_DISPLAY_NAME=GitLab.com \
  -e GITLAB_CLIENT_ID=your-oauth-app-id \
  -e GITLAB_CLIENT_SECRET=your-oauth-app-secret \
  -e GITLAB_DOMAIN=https://gitlab.com \
  silex

Silex is now running at http://localhost:6805. Log in with your GitLab account to see your websites.

With Docker Compose¶

Create docker-compose.yml in the repository root:

services:
  silex:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: silex
    ports:
      - "6805:6805"
    environment:
      SILEX_SESSION_SECRET: ${SILEX_SESSION_SECRET}
      SILEX_URL: http://localhost:6805
      STORAGE_CONNECTORS: gitlab
      HOSTING_CONNECTORS: gitlab
      GITLAB_DISPLAY_NAME: GitLab.com
      GITLAB_CLIENT_ID: your-oauth-app-id
      GITLAB_CLIENT_SECRET: your-oauth-app-secret
      GITLAB_DOMAIN: https://gitlab.com
    restart: unless-stopped

Set the session secret in a .env file next to it:

echo "SILEX_SESSION_SECRET=$(openssl rand -base64 32)" > .env

Build and start:

docker compose up -d --build

Environment variables¶

Variable	Default	Purpose
`SILEX_PORT`	6805	Internal port the Node server listens on
`SILEX_HOST`	localhost	Internal hostname (keep as localhost in Docker)
`SILEX_PROTOCOL`	http	Protocol before a reverse proxy (http or https)
`SILEX_URL`	http://localhost:6805	Public URL users visit (update for production)
`SILEX_SESSION_SECRET`	(none)	Session encryption key, random and at least 32 chars
`SILEX_SESSION_NAME`	silex-session	Session cookie name
`SILEX_DEBUG`	false	Set to true to reload the client config file on each request (dev only)
`STORAGE_CONNECTORS`	fs	Comma-separated: gitlab. The default, `fs`, is for development only
`HOSTING_CONNECTORS`	fs	Comma-separated: gitlab. The default, `fs`, is for development only
`SILEX_SERVER_CONFIG`	(none)	Path to your own server config file. The built-in `server/deploy/.silex.js` is always loaded after it
`SILEX_CLIENT_CONFIG`	(built-in SaaS config)	Path to a custom client config file

Express request limits¶

For large file uploads or large JSON payloads:

Variable	Default	Purpose
`SILEX_EXPRESS_JSON_LIMIT`	1mb	Max JSON request body
`SILEX_EXPRESS_TEXT_LIMIT`	10mb	Max text request body
`SILEX_EXPRESS_URLENCODED_LIMIT`	1mb	Max URL-encoded request body

environment:
  SILEX_EXPRESS_JSON_LIMIT: 50mb
  SILEX_EXPRESS_TEXT_LIMIT: 50mb

GitLab connectors¶

To enable GitLab storage and hosting:

environment:
  STORAGE_CONNECTORS: gitlab
  HOSTING_CONNECTORS: gitlab
  GITLAB_DISPLAY_NAME: GitLab.com
  GITLAB_CLIENT_ID: your-oauth-app-id
  GITLAB_CLIENT_SECRET: your-oauth-app-secret
  GITLAB_DOMAIN: https://gitlab.com

For a second GitLab instance, add GITLAB2_* variables and append gitlab2 to the connector lists. See Storage connectors for OAuth setup.

Reverse proxy with Caddy¶

Caddy auto-manages SSL certificates. Add it to your docker-compose.yml:

services:
  silex:
    build:
      context: .
      dockerfile: Dockerfile
    expose:
      - 6805
    environment:
      SILEX_URL: https://silex.example.com
      SILEX_PROTOCOL: https
      SILEX_SESSION_SECRET: ${SILEX_SESSION_SECRET}
      STORAGE_CONNECTORS: gitlab
      HOSTING_CONNECTORS: gitlab
      GITLAB_DISPLAY_NAME: GitLab.com
      GITLAB_CLIENT_ID: your-oauth-app-id
      GITLAB_CLIENT_SECRET: your-oauth-app-secret
      GITLAB_DOMAIN: https://gitlab.com
    restart: unless-stopped

  caddy:
    image: caddy:latest
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy-data:/data
    depends_on:
      - silex

volumes:
  caddy-data:

Create a Caddyfile:

silex.example.com {
  reverse_proxy silex:6805
}

Point your domain's A record to your server, then docker compose up -d --build. Caddy provisions and renews the certificate automatically.

Data persistence¶

With the GitLab connectors, websites are stored in GitLab repositories, not in the container. There is no volume to mount or back up.

Updating¶

Pull the latest code and rebuild:

git pull
git submodule update --init --recursive
docker compose up -d --build

Troubleshooting¶

Container fails to start¶

docker compose logs silex

Common issues:

Port 6805 already in use: change ports to ["8080:6805"]
SILEX_SESSION_SECRET too short: must be at least 32 characters

CORS errors¶

If the editor and API are on different domains:

environment:
  SILEX_CORS_URL: https://your-domain.com