Reference

Download binaries

You can download the backend, edge server and CLI for Linux and macOS, check them, and run them without Docker.

Before you start

You run Linux (x86_64 or arm64) or macOS on Apple silicon. The Linux builds need glibc 2.35 or later (Ubuntu 22.04, Debian 12, RHEL 9 or newer) and OpenSSL 3. There are no builds for Intel Macs; use the Docker images there.
For the backend, you have PostgreSQL 15 or later with an empty database, and openssl to generate the encryption key.
Port 8080 is free. The backend serves the API and the admin UI on it.

Every FluxGate release has one archive for each component and platform. You download the archives you need, check them against SHA256SUMS, unpack them, and start each binary from its folder. The binaries read config.toml and log4rs.yaml from the folder you start them in. Both files are in the archive.

Archive	Contents
`fluxgate-backend-<version>-<platform>.tar.gz`	`fluxgate-backend` (admin UI and REST API on 8080, gRPC on 50051), the UI files in `ui/`, `config.toml`, `log4rs.yaml`
`fluxgate-edge-<version>-<platform>.tar.gz`	`fluxgate-edge` (evaluation API on 8081), `config.toml`, `log4rs.yaml`, `CONFIG.md`
`fluxgate-<version>-<platform>.tar.gz`	The `fluxgate` command line client and its `README.md`

The database migrations are built into fluxgate-backend. It applies them when it starts, so there are no SQL files to run first.

Downloads for v2.0.1

Platform	Backend	Edge server	CLI
Linux x86_64	backend	edge	cli
Linux arm64	backend	edge	cli
macOS Apple silicon	backend	edge	cli

Checksums: SHA256SUMS. The Docker images of the same release are forgeopslabs/flux-gate-backend:v2.0.1, forgeopslabs/flux-gate-ui:v2.0.1 and forgeopslabs/flux-gate-edge:v2.0.1.

CI templates

Templates that run fluxgate code-refs scan in your CI and upload where each flag is used (see Code references):

Template	Use
`fluxgate-code-refs.github.yml`	GitHub Actions workflow. Copy it to `.github/workflows/`
`fluxgate-code-refs.gitlab-ci.yml`	GitLab CI job. Copy it, or include it with `include: remote:` and `integrity`

Both download the CLI archive of the release you name from this site, check it against SHA256SUMS, and scan.

Install the binaries

Set the platform and download the archives and the checksum file. Use linux-x86_64, linux-arm64 or macos-arm64:

bash

PLATFORM=linux-x86_64
BASE=https://flux.forgeopslabs.com/downloads/releases/v2.0.1
for name in fluxgate-backend fluxgate-edge fluxgate; do curl -fsSLO "$BASE/$name-v2.0.1-$PLATFORM.tar.gz"; done
curl -fsSLO "$BASE/SHA256SUMS"

Check the archives. Each line must end in OK:

bash

# Linux
sha256sum --ignore-missing -c SHA256SUMS
# macOS
shasum -a 256 --ignore-missing -c SHA256SUMS

Unpack each archive into its own folder, backend, edge and cli:

bash

mkdir -p backend edge cli
tar -xzf "fluxgate-backend-v2.0.1-$PLATFORM.tar.gz" -C backend
tar -xzf "fluxgate-edge-v2.0.1-$PLATFORM.tar.gz" -C edge
tar -xzf "fluxgate-v2.0.1-$PLATFORM.tar.gz" -C cli

Put the CLI on your PATH:

bash

sudo install -m 755 cli/fluxgate /usr/local/bin/fluxgate
fluxgate --version

Start the backend from its folder. Generate the encryption key once and keep the file:

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 backend creates its tables on the first start and applies the migrations of a newer release when you upgrade. It keeps running in this terminal.

Open http://localhost:8080. With no users yet, FluxGate redirects you to /create-admin. Create the first admin and sign in, as in Install.

Start the edge server after you create a client in the admin UI, as described in Clients and edge server. Use a new terminal in the download folder:

bash

cd edge
export EDGE_BACKEND_GRPC=http://localhost:50051
export EDGE_CLIENT_ID=<client id>
export EDGE_CLIENT_SECRET=<client secret>
./fluxgate-edge

Good to know

The settings in config.toml and the environment variables are the same as for the images. See Configuration.
EDGE_* environment variables override the edge config.toml. Prefer them for the client secret, so that the secret stays out of the file.
The backend serves the UI from ui/ because config.toml sets ui_dir = "ui". The UI calls the API on the address you opened it at. If browsers reach the backend at another address, such as https://flags.example.com, set allowed_origin in config.toml to that address.
The default log4rs.yaml writes to the console and to logs/app.log in the folder you start the binary in.
Run the binaries under a service manager such as systemd or launchd in production, so that they restart after a crash or reboot. Install has a systemd example.
The Linux backend has SAML single sign-on. The macOS backend is built without it: OpenID Connect works there, SAML providers do not.

Troubleshooting

macOS says the binary cannot be opened

The binaries are not signed. Remove the quarantine attribute that the browser added, then start the binary again:

bash

xattr -d com.apple.quarantine ./fluxgate-backend

Files downloaded with curl do not get the attribute.

Linux says `GLIBC_2.xx not found` or `libssl.so.3` is missing

The system is older than the builds need. Use a distribution with glibc 2.35 or later and OpenSSL 3, or run the Docker images instead.

The backend exits with `DATABASE_URL must be set`

Export DATABASE_URL in the shell that starts the backend. The backend does not read it from config.toml.

`curl` fails with `error: 403`

curl: (22) The requested URL returned error: 403 means the network in front of the site answered with a bot check ("Just a moment...") instead of the file. It mostly meets CI runners in cloud networks. Download from another network, or keep a copy of the release on your own mirror and point FLUXGATE_DOWNLOAD_BASE of the CI templates at it. Without -f, curl saves that page instead, and the checksum check or tar fails.