Skip to main content

Deployment Guide

This guide covers how to deploy the Sigilweaver Loom server and hub components using Docker. This is suitable for both self-hosted environments and cloud deployments.

Prerequisites​

Quick Start (Production)​

To get Sigilweaver Loom up and running quickly, follow these steps:

1. Clone the Repository or Download Docker Files​

You'll need the docker-compose.yml and related configuration files.

git clone https://github.com/Sigilweaver/Loom.git
cd Loom/docker

2. Configure Environment Variables​

Copy the example environment file:

cp .env.example .env

Edit .env to set your domain and other configuration options.

3. Generate Secrets​

Sigilweaver Loom requires several secret keys for secure operation. Run the following commands to generate them:

mkdir -p .secrets

# Session secret for web interface security
openssl rand -hex 32 > .secrets/session_secret

# Secret key for signing tokens
openssl rand -hex 32 > .secrets/secret_key

# Secret for registering new servers to the hub
openssl rand -hex 32 > .secrets/server_registration_secret

# Database password
openssl rand -hex 16 > .secrets/postgres_password

# Encryption key for database connections
python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())" > .secrets/connection_encryption_key
Important

All secrets must be changed from their defaults. In production (ENVIRONMENT=production), Hub will refuse to start if SESSION_SECRET or SECRET_KEY are still set to CHANGE_ME_IN_PRODUCTION. In development mode (the default), a warning is logged instead. If SERVER_REGISTRATION_SECRET is empty, Hub will log a warning — any server can register without authentication.

4. Build and Start​

Build the containers and start the stack in detached mode:

docker compose build
docker compose up -d

5. Verify Deployment​

Check the status of your containers:

docker compose ps

You can view logs with:

docker compose logs -f

Architecture​

The deployment consists of several services:

  • Hub: The central orchestration platform (FastAPI + React).
  • Server: The execution engine (Python + Polars).
  • Postgres: Database for the Hub.
  • Nginx (Optional): Reverse proxy (you may use your own).

Updates​

To update your deployment to the latest version:

git pull
docker compose build --pull
docker compose up -d

Troubleshooting​

If containers fail to start, check the logs for specific error messages:

docker compose logs service_name