Deploy to Cloud

This guide deploys Openfuse on a cloud VM with a real domain, TLS certificates, and optionally a managed database. Use it for team evaluations, staging environments, or automated CI pipelines.

If you just want to try Openfuse on your laptop, start with Try Locally instead.

Prerequisites

• A Linux VM (Ubuntu 22.04+, Debian 12+, or Amazon Linux 2023)
• A domain with DNS access
• Docker and Docker Compose v2 installed

Install Docker (if needed)

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
# Log out and back in, then verify:
docker compose version

1. Set up DNS

Openfuse needs three DNS records pointing to your VM's public IP:

Replace openfuse.example.com with your chosen domain. You can use any subdomain of a domain you control.

Verify DNS has propagated before continuing:

dig +short openfuse.example.com
dig +short test.openfuse.example.com
dig +short test.api.openfuse.example.com
# All three should return your VM's IP

2. Open ports

Ensure ports 80 and 443 are open in your VM's firewall or security group. Caddy needs port 80 for ACME HTTP-01 certificate validation and port 443 for HTTPS traffic.

3. Run the installer

SSH into your VM and run the installer in non-interactive mode. Set the required environment variables and pass --ci:

export ROOT_DOMAIN=openfuse.example.com
export ROOT_USER_EMAIL=admin@example.com
export ROOT_USER_PASSWORD='YourStr0ng!Password'

# SMTP (optional — omit to skip email features)
export SMTP_HOST=smtp.example.com
export SMTP_USER=smtp-user
export SMTP_PASSWORD=smtp-password

# Install and start
curl -sSL https://get.openfuse.io/install | bash -s -- --ci --version 1.2.0
cd openfuse && docker compose up -d

The --ci flag:

• Reads all values from environment variables (fails fast if required ones are missing)
• Auto-generates secrets that aren't provided (client secrets, session secret, DB password)
• Skips all interactive prompts
• Detects external databases when DATABASE_HOST is set

Using an external database

If you have a managed PostgreSQL instance (RDS, Cloud SQL, Azure Database), pass the connection details:

export DATABASE_HOST=your-rds-endpoint.amazonaws.com
export DATABASE_PASSWORD=your-db-password
export DATABASE_SSL=true

# Then run the installer as above
curl -sSL https://get.openfuse.io/install | bash -s -- --ci --version 1.2.0

You need to create two databases on your PostgreSQL server beforehand: openfuse and keycloak. The API and Keycloak handle their own schema setup on first run.

4. Verify the deployment

Once docker compose ps shows all services as healthy:

Sign in with the admin credentials you set, create a company, and generate SDK credentials from the dashboard.

CI pipeline example

Here's a GitHub Actions workflow that deploys Openfuse to a VM for integration testing:

name: Integration Tests with Openfuse
on: [pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Start Openfuse
        env:
          ROOT_DOMAIN: lvh.me
          ROOT_USER_EMAIL: admin@test.com
          ROOT_USER_PASSWORD: Test1234!@#$
        run: |
          curl -sSL https://get.openfuse.io/install | bash -s -- --ci
          cd openfuse && docker compose up -d
          # Wait for API to be healthy
          timeout 120 bash -c 'until curl -sf https://admin.api.lvh.me/health; do sleep 5; done'

      - name: Run tests
        run: pnpm test

SMTP providers

For team evaluations, configure SMTP so invites and password resets work:

Next steps