Deploying Flux

Flux is designed to be incredibly easy to deploy. Because it is a single binary with zero external dependencies, you don't need to install language runtimes (like Node or Python) or configure complex database servers.

This guide covers deploying Flux on a standard Linux VPS (like DigitalOcean, Linode, or AWS EC2).

This method sets up Flux as a background service managed by the system, ensuring it restarts automatically if the server reboots.

1. Prepare the Server

Connect to your server and create a dedicated user and directory for Flux. This isolates the application for better security.

# Create a dedicated user
sudo useradd -r -s /bin/false flux

# Create directories
sudo mkdir -p /opt/flux/data

# Download the binary (Replace URL with latest release)
cd /opt/flux
sudo wget [https://github.com/otaleghani/flux/releases/latest/download/flux_linux_amd64](https://github.com/otaleghani/flux/releases/latest/download/flux_linux_amd64) -O flux

# Make executable
sudo chmod +x flux

# Set ownership
sudo chown -R flux:flux /opt/flux

2. Create a Systemd Service

Create a configuration file to tell Linux how to run Flux in the background.

sudo nano /etc/systemd/system/flux.service

Paste the following configuration:

[Unit]
Description=Flux Form Server
After=network.target

[Service]
# Run as the dedicated user
User=flux
Group=flux

# working directory
WorkingDirectory=/opt/flux

# Environment Variables
Environment="PORT=8080"
Environment="SSH_PORT=2222"
Environment="DB_PATH=data/flux.db"
# OPTIONAL: Auto-unlock (Uncomment if you want auto-restarts)
# Environment="FLUX_KEY=your-master-password" 

# The command to run
ExecStart=/opt/flux/flux

# Restart automatically if it crashes
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

3. Start the Service

Enable and start Flux.

sudo systemctl daemon-reload
sudo systemctl enable flux
sudo systemctl start flux

You can check the status with sudo systemctl status flux.

Option 2: Docker Deployment

If you prefer containers, Flux is easy to containerize.

Dockerfile

Create a Dockerfile in your project root:

FROM alpine:latest

# Install CA certificates for HTTPS requests (SMTP/Turnstile)
RUN apk add --no-cache ca-certificates

WORKDIR /app

# Copy binary (Assuming you built it locally or downloaded it)
COPY flux /app/flux

# Create data directory
RUN mkdir /app/data

# Expose ports
EXPOSE 8080 2222

CMD ["./flux"]

Docker Compose

The easiest way to run it is with Compose.

version: '3.8'
services:
  flux:
    build: .
    ports:
      - "8080:8080"
      - "2222:2222"
    volumes:
      - ./data:/app/data
    environment:
      - DB_PATH=/app/data/flux.db
      # - FLUX_KEY=my-secret-key 
    restart: unless-stopped

Setting up HTTPS (Caddy)

Regardless of how you run Flux, you should not expose port 8080 directly to the public. It is best practice to use a Reverse Proxy to handle SSL/TLS encryption.

We recommend Caddy because, like Flux, it is a single binary that handles everything automatically (including renewing SSL certificates).

1. Install Caddy

Follow the official installation instructions for your distro. For Ubuntu/Debian, it is usually:

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl 

curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg 

curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list 

sudo apt update 

sudo apt install caddy

2. Configure Caddy

Edit the Caddy configuration file:

sudo nano /etc/caddy/Caddyfile

Delete the default content and replace it with this (swap forms.example.com with your actual domain):

forms.example.com {
    reverse_proxy localhost:8080
}

That's it. You don't need to specify certificate paths.

3. Restart Caddy

Reload the service to apply changes.

sudo systemctl reload caddy

Caddy will automatically provision an SSL certificate from Let's Encrypt and start serving your Flux instance securely over HTTPS.

Post-Deployment Checklist

  1. SSH Access: From your local machine, verify you can access the Flux admin TUI.
	ssh -p 2222 [email protected]
  • Note: You may need to open port 2222 in your cloud firewall (AWS Security Groups / DigitalOcean Firewall).
  1. Unlocking: If you did not set the FLUX_KEY environment variable, your database will be Sealed after deployment. You must SSH in and enter your password to start accepting submissions.
  2. Backups: Backing up Flux is trivial. You only need to save one file, /opt/flux/data/flux.db. You can set up a simple cron job to copy this file to an S3 bucket or another server nightly.