Completing a Docker Compose deployment

Install Docker

We recommend that you start with a freshly installed OS on a virtual private server (VPS) that does not contain any other services.

Otherwise, you might encounter issues with occupied ports or incompatible libraries that this guide does not cover.

For details on how to install Docker, go to the Docker documentation.

Supported architectures

The supported CPU architectures are:

• AMD64 (x86-64)

• ARM64 (aarch64)

This guide uses Ubuntu 24.04 LTS.

Notes on the Docker installation

Standard installation that runs under root

This guide uses a standard Docker installation where the Docker daemon runs under root as the systemd service. Containers that run unprivileged and application processes inside containers operate as non-root users.

This configuration allows exposing to containers additional Linux capabilities (syscalls) that are not available by default in more restricted environments, and that cannot be granted in Docker Rootless mode. Fabricate relies on these low-level syscalls, such as SYS_PTRACE, for its JavaScript sandbox isolation.

This setup also allows binding to privileged ports (< 1024) and running a load balancer / proxy alongside other services without additional host-system configuration changes, such as modifying net.ipv4.ip_unprivileged_port_start.

Default runc runtime

This guide uses Docker with the default runtime runc.

Alternative runtimes that have more strict per-container microVM or user-space kernel isolation, such as kata-runtime (Kata Containers) or runcs (gVisor), are not supported, and might not work correctly, because they might not implement or expose all of the required syscalls.

For more information, go to Docker runtimes in the Docker documentation.

Pull Docker images

The Fabricate Docker image is available to Enterprise customers on Quay.io.

This guide uses the latest tag, so that you always pull the latest available Fabricate version. For a production setup, we recommend that you instead pin Docker images to specific versions.

First, log in to the registry with the credentials that Tonic.ai provided:

docker login -u='<username>' -p='<password>' quay.io

Next, run the following command to pull the main application image:

docker pull quay.io/tonicai/fabricate:latest

Next, pull the application PDF sidecar image:

docker pull quay.io/tonicai/fabricate-html-to-pdf-sidecar:latest

Prepare the .env file

Fabricate requires several environment variables.

Create the working directory

First, create a directory for the .env and docker-compose.yml template files.

mkdir -p ./fabricate
cd ./fabricate

Copy the .env template

The template file is available in the GitHub repository https://github.com/TonicAI/fabricate_docker_compose/blob/main/.template.env. Copy the .template.env file from the repository into the directory as .env. The template contains the available environment variables with descriptions.

The commented-out variables are not immediately needed.

Configure SECRET_KEY_BASE

You must configure SECRET_KEY_BASE.

To generate a new secret key for your instance, run the following command:

docker run --rm quay.io/tonicai/fabricate:latest /fabricate/bin/rails secret

Save the output in .env:

SECRET_KEY_BASE="a941ffd00cffe765877685557323dbf5f23e266ee41c45240141941b53e6e417edbf9a016ef932d1d7e208e1de2a2010d482eab03"

Configure FABRICATE_HOST

The FABRICATE_HOST environment variable defines the host for which Fabricate accepts requests and generates links. Fabricate rejects requests for other hosts.

This should be the domain where you host Fabricate. If you do not have one yet, you can keep localhost:3000 for now and change it later.

For example:

FABRICATE_HOST="fabricate.localhost:3000"

Configure FABRICATE_ADMIN_EMAIL

The FABRICATE_ADMIN_EMAIL environment variable defines the email address of the first admin user.

When a user signs up for Fabricate with this email address, they receive access to the Admin Console and are granted full control over the Fabricate instance.

To ensure that you can complete the first signup, this must be a working email address.

For example:

[email protected]

Configure FABRICATE_MAIL_*

The FABRICATE_MAIL_* environment variables configure the SMTP service for outgoing email messages from Fabricate.

You can use:

• Amazon Simple Email Service (Amazon SES) with SMTP credentials

• Amazon SES with an IAM role

• A dedicated mailbox for Fabricate under your organization

• Another SMTP provider

If you do not configure this correctly, you will not be able to sign up to Fabricate, because you will not receive the confirmation email message.

For example:

FABRICATE_MAIL_ADDRESS=email-smtp.us-west-2.amazonaws.com
FABRICATE_MAIL_PORT=587
FABRICATE_MAIL_USER_NAME=
FABRICATE_MAIL_PASSWORD=
[email protected]

Note that if you SMTP server enforces it, FABRICATE_MAIL_FROM must match the mailbox email address.

To improve security and deliverability, and to reduce the chance that email messages are flagged as spam, we also recommend that you set up SPF, DKIM, and DMARC DNS records for your domain.

Configure your LLM Provider

Fabricate AI features rely on an external LLM provider. You must configure a connection to either Amazon Bedrock, Anthropic, or Azure AI Foundry.

In the .env file, uncomment and configure the settings for the provider that you want to use. The settings include the API key to use for that provider.

For example, to use Anthropic:

FABRICATE_ANTHROPIC_API_KEY="sk-asdf"
FABRICATE_ANTHROPIC_BASE_URL="https://api.anthropic.com"

Optional: Configure FABRICATE_BLOCK_STORAGE_SERVICE

By default, Fabricate uses local storage for generated assets, PDF files, and similar data.

To use an external Amazon S3-compatible storage service, in the .env file, configure the FABRICATE_BLOCK_STORAGE_SERVICE environment variable.

To use Amazon S3 instead:

1. Set:

FABRICATE_BLOCK_STORAGE_SERVICE="amazon"

1. Configure the Amazon S3 details:

FABRICATE_S3_BUCKET="fabricate"
FABRICATE_AWS_REGION="us-east-1"
# FABRICATE_AWS_ACCESS_KEY_ID=
# FABRICATE_AWS_SECRET_ACCESS_KEY=

Prepare docker-compose.yml

The Docker Compose file is available in the GitHub repository https://github.com/TonicAI/fabricate_docker_compose/blob/main/docker-compose.yaml. Copy the docker-compose.yaml template into the ./fabricate folder with the .env file.

The template contains prefilled database credentials, connection strings, storage paths, socket paths, and ports. These values are loaded from the previously created .env file.

However, you must change the:

• The PostgreSQL credentials.

• The Redis credentials.

Start the services

For the first run, start the services in the foreground:

docker compose up

If the containers start cleanly, stop them with Ctrl+C.

Next, run the services in detached mode:

docker compose up -d

Persistent data is stored locally in Docker volumes.

Fabricate now runs and listens on HTTP port 3000 on the instance.

Configure the load balancer

To obtain an HTTPS certificate and expose it on the internet, you configure an HTTP/s load balancer.

You can use either:

• AWS Application Load Balancer (ALB).

  • Uses an AWS Certificate Manager (ACM) certificate.

  • Managed by AWS.

  • DNS points to ALB.

• Caddy

  • Uses a Let's Encrypt certificate.

  • Runs on the same VPS.

  • DNS points to the VPS.

AWS ALB

This is the recommended setup on AWS.

1. In AWS Certificate Manager (ACM), issue a certificate for your hostname, such as fabricate.example.com , using a DNS or Email challenge.

2. Create new target group (at EC2 / Load Balancing / Target Groups) with:

   • Protocol HTTP

   • Port 3000

   • Health check path /up

3. Register the used Amazon EC2 instance in that target group.

4. Create a new application load balancer under EC2 / Load Balancing / Load balancers with:

   • HTTPS (443) forwarding to the target group

   • Optional HTTP (80) redirecting to HTTPS

   • Previously issued ACM certificate for your domain

   • Previously created target group with the Amazon EC2 instance

5. Allow 443 on the ALB security group.

6. Allow 3000 on the instance only from the ALB security group.

7. Point DNS for your hostname to the ALB CNAME / A / AAAA.

Update .env:

FABRICATE_HOST="fabricate.example.com"

To apply the changes, restart the stack:

docker compose up -d --force-recreate

Caddy on the same VPS

Use this option when you want Transport Layer Security (TLS) termination on the server itself.

1. Add an A or AAAA record for your hostname (such as fabricate.example.com) that points to the server IP address.

2. Allow inbound TCP 80 and 443 connections. Note that publishing 80:80 and 443:443 requires a standard rootful Docker install on a VPS, such as Ubuntu with Docker Engine from Docker’s packages. If you use rootless Docker, binding those host ports often fails unless you allow unprivileged low ports on the host. For example, net.ipv4.ip_unprivileged_port_start=0.

3. Add the following additional caddy service to your existing docker-compose.yml file:

services:
  caddy:
    image: caddy:latest
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy_data:/data
      - caddy_config:/config
    extra_hosts:
      - "host.docker.internal:host-gateway"
    networks:
      - fabricate_internal
      
volumes:
  caddy_data:
  caddy_config:

1. In the same directory, create a Caddyfile configuration with a proxy to the http://web:3000 container. Caddy uses ACME HTTP challenge to automatically issue and renew the certificate for your domain.

fabricate.example.com {
  reverse_proxy http://web:3000
  tls {
    protocols tls1.2 tls1.3
  }
}

1. Update .env:

FABRICATE_HOST="fabricate.example.com"

1. To apply the changes, restart the stack:

docker compose -f docker-compose.yml up -d --force-recreate

Create the admin account

Next, go to https://fabricate.example.com .

Sign up as a new user. Use the email address that you configured as the value of FABRICATE_ADMIN_EMAIL.

After you activate the account from the confirmation email message, you can sign in and use the Admin Console.

Next steps

Your Fabricate instance is now ready to accept traffic.

For more information about Fabricate configuration options, go to Configuring Fabricate.

For information on how to use the the Admin Console to manage your Fabricate instance, go to Using the Admin Console.