Installation

Deploying Galleon takes the server itself and PostgreSQL. The server is a single process, it accepts requests on port 8080 by default and can serve HTTPS itself once a certificate and a key are set (TLS). PostgreSQL holds the metadata of the installation. A reverse proxy is deployed in front of the server when needed (Reverse proxy).

The artifacts themselves are stored as files in the storage directory on the server disk (see Storage and garbage collection).

System requirements

Minimum server requirements:

• CPU and memory: 4 vCPU and 4 GB RAM.
• Disk: the server itself needs almost no disk space — the volume is determined by the stored artifacts (the storage directory) and the database.
• PostgreSQL version 16 or newer. With the default server settings, the database needs max_connections of at least 110.
• The database and the role named in the configuration are created in advance. Galleon connects to the database and runs migrations as that role, so the role needs rights to create tables and the pg_stat_statements extension.

First start

The minimal configuration is four blocks (the full parameter reference is in Configuration parameters):

database:
  host: localhost
  port: 5432
  user: galleon
  password_env: GALLEON_DATABASE_PASSWORD
  dbname: galleon

storage:
  default:
    type: local
    local:
      root: /var/lib/galleon/data

security:
  secret_key_file: /etc/galleon/secret-key.yaml

auth:
  bootstrap_admin:
    username: admin
    password_env: GALLEON_BOOTSTRAP_ADMIN_PASSWORD

To start the server, follow these steps:

1. Save the configuration to a file, for example /etc/galleon/config.yaml.

2. Create the encryption key and store it in the key file (see Secrets and the encryption key for details):

   openssl rand -base64 32

   # /etc/galleon/secret-key.yaml
   active: 1
   keys:
     - id: 1
       key: "<BASE64>"

3. Set the passwords in the environment variables named in the configuration:

   export GALLEON_DATABASE_PASSWORD='<database password>'
   export GALLEON_BOOTSTRAP_ADMIN_PASSWORD='<first administrator password>'

4. Start the server:

   galleon --config /etc/galleon/config.yaml

On the first start, Galleon creates the first administrator and the starter set of repositories.

Migrations at startup

By default, the server brings the database schema to the required version and continues serving — no separate step is needed. When the instance has several servers, one of them runs the migrations while the others wait their turn and start once the schema is ready.

The migrations can be moved into a separate run — to update the schema before rolling out a new version, for example. Two mutually exclusive flags do that:

• --migrate-only — apply the migrations and exit without starting to serve;
• --skip-migrate — do not apply the migrations, but check that the schema is not older than the required one and start serving. If it is older, the server does not start.

If the database is still booting at startup, the server exits at once. To make the server wait for the database, set a waiting budget:

database:
  migrate_wait: 5m

The waiting covers only the signs of “the database is not ready yet”: a refused connection, an unresolvable name, a connection timeout, a database server that is starting up or recovering, a missing database. Wrong credentials are not covered — the server exits at once.

The exit code separates a temporary cause from one that needs attention:

The migrations can be interrupted at any moment. The unfinished step is rolled back whole, and the next start resumes from it.

Verification

Make sure the server responds:

curl http://localhost:8080/healthz
curl http://localhost:8080/readyz

healthz confirms the process is alive; readyz — that the database is reachable. See Monitoring for details.