@fluxup/installer

CLI for deploying the FluxUp platform on-premises using Docker Compose.

npx @fluxup/installer

What is this?

@fluxup/installer automates deployment and updates of FluxUp on a Linux server with Docker. Running npx @fluxup/installer in a directory that already has a FluxUp installation automatically switches to update mode.

First install:

1. Activation token validation against the FluxUp Token Vending Machine (TVM)
2. Interactive wizard to collect database and network configuration
3. GHCR authentication using credentials delivered by the TVM
4. Download of docker-compose.yml from S3 via presigned URL
5. Generation of the .env file with all runtime variables
6. docker compose pull + docker compose up to start all services

Update (existing install detected):

1. Activation token validation (re-issues fresh credentials from the TVM)
2. Download of the latest docker-compose.yml from S3
3. Version diff table — shows installed vs. available image tags for each service
4. Confirmation prompt before proceeding
5. docker compose pull + docker compose up with the updated compose file
6. .env refreshed with new credentials from the TVM

Activation token

An activation token is required to run the installer.

The token authenticates your installation and triggers the TVM to issue per-tenant AWS credentials, a presigned S3 URL for docker-compose.yml, and a GHCR token. Without a valid token the installer will abort.

To request a token, contact: [email protected]

Prerequisites

| Tool | Minimum version | Notes | |---|---|---| | Docker Engine | 20.10 | Must be running | | Docker Compose | v2 | docker compose version must work | | Node.js | 18 | Only needed for npx — can be removed after install |

How to run

Install (new server)

npx @fluxup/installer

The wizard will ask for:

1. Activation token — validated against the TVM before proceeding
2. Database password (DB_PASSWORD)
3. Database host port (DB_PORT, default 5432)
4. HTTP port (NGINX_PORT, default 80)

Update (existing install)

Run the same command in the same directory:

npx @fluxup/installer --dir /opt/fluxup

The installer detects the existing docker-compose.yml and .env and automatically enters update mode. It shows a version diff before applying changes:

Service        Installed            Available
──────────────────────────────────────────────────────
backend        1.4.2                1.5.0          ↑ update
bff            1.4.2                1.5.0          ↑ update
frontend       1.4.2                1.5.0          ↑ update
connector      0.9.1                0.9.1          ✓
postgres       18                   18             ✓

Available flags

| Flag | Description | |---|---| | --dir <path> | Installation directory (default: ./fluxup) | | --non-interactive | Reads variables from shell environment — useful for CI/automation | | --no-pull | Skips docker compose pull | | --local-compose | Uses compose/docker-compose.yml from the package source instead of downloading from S3 — development only | | --update / -u | Clears the npx cache and reruns with @fluxup/installer@latest — ensures the newest installer version is used |

Updating the installer itself

If you want to force npx to fetch the latest installer version (bypassing its local cache):

npx @fluxup/installer --update

This clears the npm/npx cache and relaunches the installer as @latest. All other flags are forwarded:

npx @fluxup/installer --update --dir /opt/fluxup

Non-interactive mode (CI/automation)

Export the required variables before running:

export FLUXUP_INSTALL_TOKEN="fxp_install_..."

export DB_PASSWORD="..."
export DB_PORT="5432"
export NGINX_PORT="80"

npx @fluxup/installer --non-interactive --dir /opt/fluxup

Works for both fresh installs and updates. GHCR token, compose URL, AWS credentials, and Secrets Manager ARN are all delivered at activation time — they do not need to be set manually.

Post-install management

The installer writes a fluxup.sh helper to the installation directory. Use it for all Docker Compose operations — it always passes --env-file correctly:

cd /opt/fluxup

./fluxup.sh ps        # container status
./fluxup.sh logs -f   # real-time logs
./fluxup.sh down      # stop all services
./fluxup.sh up -d     # restart

Never run docker compose manually without --env-file .env — environment variables will be empty and services will fail to connect.

Troubleshooting

password authentication failed for user "..."

Occurs on reinstalls: PostgreSQL only applies POSTGRES_PASSWORD on first initialization. If a postgres_data volume already exists with a different password, the container ignores the new value.

The installer automatically syncs the password via ALTER USER after up. To do it manually:

docker exec fluxup_postgres psql -U fluxup -c "ALTER USER fluxup WITH PASSWORD 'new_password';"

To wipe all data and reinitialize from scratch:

./fluxup.sh down -v   # removes volumes
./fluxup.sh up -d

ports are not available / port in use

The installer validates ports before pulling images. If a port is in use, it aborts with a clear message.

On WSL2/Docker Desktop, binding to 127.0.0.1 sometimes fails even when the port appears free. Fix by setting DB_BIND_HOST=0.0.0.0 before running:

export DB_BIND_HOST=0.0.0.0
npx @fluxup/installer

View service logs

Containers log to stdout (no files). Use:

./fluxup.sh logs backend    # backend logs
./fluxup.sh logs -f         # all services, real-time

Contact

Questions or support: [email protected]