Chapter 1 · Get started

Install and first boot

You can run the full FluxGate stack locally with Docker Compose and create the first admin in under five minutes.

3:39 videoBuilds on:What is FluxGate

Before you start

Docker with Docker Compose, and openssl, are installed.
You have an empty folder to work in.
Ports 3000, 8080 and 5433 are free on your machine. Port 8081 must be free when you start the edge server later.

The images come from Docker Hub (forgeopslabs/flux-gate-backend, forgeopslabs/flux-gate-ui and forgeopslabs/flux-gate-edge, tag v2.0.1). You do not need a source checkout and you do not build anything.

What you will do

The demo files start PostgreSQL, the backend and the admin UI. They also define the edge server, but it stays stopped until you connect an app. You generate one secret, start the stack, and create the first admin in the UI.

You need two files:

docker-compose.demo.yml describes the containers.
config.demo.toml is the backend configuration. The compose file mounts it into the backend container.

config.demo.toml has these keys:

Key	Demo value	Meaning
`allowed_origin`	`http://localhost:3000`	The browser origin the backend accepts for cross-origin requests. It points at the UI.
`http_addr`	`0.0.0.0:8080`	Where the REST server listens.
`grpc_addr`	`0.0.0.0:50051`	Where the gRPC server listens.
`public_base_url`	unset	The address browsers and identity providers use to reach the backend. Single sign-on callbacks are built from it. Leave it unset on localhost.

Install FluxGate

Download the two files into the empty folder, so that both sit side by side:

bash

curl -fsSLO https://flux.forgeopslabs.com/downloads/docker-compose.demo.yml
curl -fsSLO https://flux.forgeopslabs.com/downloads/config.demo.toml

Generate the encryption key and write it to a file named .env next to the compose file. Run this command once:
bash
```
echo FLUXGATE_ENCRYPTION_KEY=$(openssl rand -base64 32) > .env
```
Start the stack. Compose reads the key from .env on its own:
bash
```
docker compose -f docker-compose.demo.yml up -d
```
Three containers start: PostgreSQL, the backend and the UI. The backend runs its database migrations at startup, so there is no schema step.
Check the containers. Wait until the backend shows Up:
bash
```
docker compose -f docker-compose.demo.yml ps
```
Open http://localhost:3000. With no users yet, FluxGate redirects you to /create-admin.
On Create Admin Account, fill Username with admin, then Password, Confirm Password, First Name, Last Name and Email. Click Create Admin. This account has full control of the instance.
FluxGate returns you to the sign-in page, Sign in to FluxGate. Enter the credentials you just created and click Sign in.
You land on System Overview at /. The cards are empty because no features, clients or evaluations exist yet.

The create-admin page appears only once, on a fresh database.

Install from the binaries

Instead of Docker, you can run the native builds of the same release. The backend serves the admin UI itself on port 8080, so you need no UI container. You bring PostgreSQL.

Check that you have what the binaries need:
- Linux x86_64 or arm64 with glibc 2.35 or later (Ubuntu 22.04, Debian 12, RHEL 9 or newer) and OpenSSL 3, or macOS on Apple silicon. There are no Intel Mac builds.
- PostgreSQL 15 or later with an empty database, for example feature_toggle.
- Port 8080 free for the backend, and 8081 for the edge server later.

Download the backend and the CLI for your platform (linux-x86_64, linux-arm64 or macos-arm64), with the checksum file:

bash

PLATFORM=linux-x86_64
BASE=https://flux.forgeopslabs.com/downloads/releases/v2.0.1
curl -fsSLO "$BASE/fluxgate-backend-v2.0.1-$PLATFORM.tar.gz"
curl -fsSLO "$BASE/fluxgate-v2.0.1-$PLATFORM.tar.gz"
curl -fsSLO "$BASE/SHA256SUMS"

Check the archives. On macOS, use shasum -a 256 instead of sha256sum. Each line must end in OK:
bash
```
sha256sum --ignore-missing -c SHA256SUMS
```

Unpack each archive into its own folder, and put the CLI on your PATH:

bash

mkdir -p backend cli
tar -xzf "fluxgate-backend-v2.0.1-$PLATFORM.tar.gz" -C backend
tar -xzf "fluxgate-v2.0.1-$PLATFORM.tar.gz" -C cli
sudo install -m 755 cli/fluxgate /usr/local/bin/fluxgate
fluxgate --version

Generate the encryption key once, then start the backend from its folder:
bash
```
cd backend
[ -f encryption.key ] || openssl rand -base64 32 > encryption.key
export FLUXGATE_ENCRYPTION_KEY=$(cat encryption.key)
export DATABASE_URL=postgres://postgres:<password>@localhost:5432/feature_toggle
./fluxgate-backend
```
The database migrations are built into the binary. The backend creates its tables on the first start, so there are no SQL files to apply.

The backend keeps running in this terminal. Use another terminal for the next commands.
Open http://localhost:8080. With no users yet, FluxGate redirects you to /create-admin. Create the first admin and sign in.

Back up encryption.key with the database: secrets stored with one key cannot be read with another. Download binaries lists every archive, including the edge server, and its troubleshooting covers unsigned macOS binaries and old Linux systems.

Run the backend as a service

In production, let a service manager start the backend and restart it after a crash or reboot. A systemd unit for a backend unpacked to /opt/fluxgate/backend, with the two secrets in /etc/fluxgate/backend.env (DATABASE_URL=... and FLUXGATE_ENCRYPTION_KEY=..., readable only by root):

/etc/systemd/system/fluxgate-backend.service

[Unit]
Description=FluxGate backend
After=network-online.target postgresql.service

[Service]
WorkingDirectory=/opt/fluxgate/backend
EnvironmentFile=/etc/fluxgate/backend.env
ExecStart=/opt/fluxgate/backend/fluxgate-backend
Restart=on-failure
User=fluxgate

[Install]
WantedBy=multi-user.target

Create the service user and give it the folder, because the backend writes logs/app.log there: sudo useradd --system fluxgate && sudo chown -R fluxgate /opt/fluxgate/backend. Then run sudo systemctl daemon-reload && sudo systemctl enable --now fluxgate-backend. On macOS, a launchd property list in /Library/LaunchDaemons with the same working directory, environment variables and KeepAlive does the same.

Examples

Expected output of `ps`

You see three services. Container names are prefixed with the folder name. The COMMAND and CREATED columns are left out here, and times differ:

Output shape

NAME                 IMAGE                           SERVICE    STATUS                    PORTS
<folder>-backend-1   forgeopslabs/flux-gate-backend:v2.0.1   backend    Up 8 seconds              0.0.0.0:8080->8080/tcp, [::]:8080->8080/tcp
<folder>-postgres-1  postgres:15                     postgres   Up 13 seconds (healthy)   0.0.0.0:5433->5432/tcp, [::]:5433->5432/tcp
<folder>-ui-1        forgeopslabs/flux-gate-ui:v2.0.1        ui         Up 8 seconds              0.0.0.0:3000->80/tcp, [::]:3000->80/tcp

The `.env` file

After this page the folder holds one .env file with one line:

.env

FLUXGATE_ENCRYPTION_KEY=<base64 of 32 bytes>

Later chapters add more lines to .env: TYPESAFE_API_KEY for the optional AI features, and EDGE_CLIENT_ID and EDGE_CLIENT_SECRET for the edge server.

Good to know

Data lives in the Docker volume pgdata. docker compose -f docker-compose.demo.yml down keeps it, so every team, flag and user is still there after the next up -d. down -v deletes the volume and all FluxGate data. After that the UI asks for a first admin again.
The UI has no proxy. Your browser calls the backend directly at http://localhost:8080, so port 8080 must be free and reachable from your browser. On a remote host, change BACKEND_HOST in the compose file and allowed_origin in config.demo.toml together.
The backend serves Swagger UI for the REST API at http://localhost:8080/docs/. Type the trailing slash: /docs without it returns 404.
The edge server does not start with up -d. It needs the ID and API key of a client that you create later, in Clients and edge server.
The images are published for both amd64 and arm64. To check that you run the expected version, run docker compose -f docker-compose.demo.yml images.

Troubleshooting

Compose says `set FLUXGATE_ENCRYPTION_KEY (openssl rand -base64 32)`

The .env file is missing, empty, or in another folder. Run the compose command from the folder that holds both docker-compose.demo.yml and .env. If the file does not exist yet, run the key command from step 2 once.

A port is already in use

Compose fails with an error such as Bind for 0.0.0.0:3000 failed: port is already allocated. Stop the program that uses the port, or change the host side of the ports entry in the compose file, for example "3100:80". If you move the UI, change allowed_origin in config.demo.toml to the new origin. If you move the backend, change BACKEND_PORT for the UI as well.

Open the browser developer tools. A CORS error means allowed_origin does not match the address in your address bar. A network error means the browser cannot reach http://localhost:8080. Check that the backend container is Up and that port 8080 is published.

Next

Create the Checkout team and the users priya and sam in Teams, users and roles.