Configuration

Once installed, Flux needs to be configured and initialized. Because Flux uses strong encryption for your secrets, the first run involves a special setup process to generate your Master Key.

Environment configuration

Flux relies on environment variables for its basic network and storage settings. You can set these in your shell to make them available to Flux.

Detailed Reference: For a complete list of options and their security implications, see Environment Variables.

Running Flux

Start the application from your terminal:

./flux

On the first run, you will see logs indicating that Flux has initialized the SQLite database in the data/ directory.

Initialization

To interact with Flux, you don't use a web dashboard. Instead, you use the secure SSH TUI (Text User Interface).

Open a new terminal window and connect to your instance:

ssh -p 2222 admin@localhost

• Port: Make sure to use the port defined in SSH_PORT (Default: 2222).
• User: The username (admin) is cosmetic; Flux handles identity internally.

First run

On your very first connection, you will be greeted by the INITIAL SETUP screen.

1. Create a Passphrase: Enter a strong, memorable password.
2. Derivation: Flux uses this password to generate the AES-GCM encryption key for your database.
3. Important: Do not lose this password.

Warning: If you lose your Master Password, your encrypted data (SMTP credentials, Captcha keys) will be permanently unrecoverable. Flux does not have a "Forgot Password" feature because it does not store your key.

Sealed state

When Flux starts, it enters a Sealed State (Locked).

• HTTP Server: Active, but returns 503 Service Unavailable for any submission requiring secrets.
• Data Access: The database is encrypted. No SMTP passwords or API keys can be read.

To start processing forms, you must unseal the instance.

Unlocking Flux

Every time you restart the Flux server (e.g., after a server reboot or update), it will return to the Sealed State.

To resume normal operations:

1. SSH into the instance: ssh -p 2222 admin@localhost
2. Enter your Master Password at the prompt.
3. Flux unlocks, decrypts the secrets into RAM, and the HTTP server begins accepting submissions immediately.

Securing SSH access (Strongly recommended)

By default, if Flux cannot find an authorized_keys file, it runs in Development Mode, allowing any SSH connection without a cryptographic key check. While convenient for local testing, this is insecure for public servers.

To secure your management interface, you must provide a list of allowed public keys.

Step 1: Generate an SSH Key

If you don't already have an SSH key pair on your computer, generate one using the modern Ed25519 algorithm:

ssh-keygen -t ed25519 -C "flux-admin"

Press Enter to accept the defaults. This creates two files in your ~/.ssh/ folder:

• id_ed25519: Your Private Key (Keep this secret).
• id_ed25519.pub: Your Public Key (Safe to share).

Step 2: Get your Public Key

Output the content of your public key:

cat ~/.ssh/id_ed25519.pub
# It will look like: ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... flux-admin

Step 3: Authorize the Key in Flux

On the server running Flux, create the authorized_keys file inside your data directory and paste your public key into it.

# Your data folder for flux is 'data/'
echo "ssh-ed25519 AAAAC3NzaC... flux-admin" >> data/authorized_keys

That's it. Flux checks this file on every connection attempt. Remember to restart flux afterwards.

• If the file exists, Flux enforces strict key authentication. Only users with a matching private key can connect.
• If the file is deleted, Flux reverts to open access (Development Mode).

Automated unlocking

If you require Flux to start automatically without manual intervention (e.g., in a Kubernetes cluster), you can provide your Master Password via the FLUX_KEY environment variable.

• Pros: Zero-touch restarts.
• Cons: Your Master Password is exposed in the environment variables, reducing security.
• Learn More: Read about the trade-offs in the Security Model.