Skip to main content

​
Prerequisites

  • Linux server (or Docker on any platform)
  • PostgreSQL 15+ (or Docker to create one automatically)
  • Go 1.24+ and a C compiler
  • A domain name (for production)

​
Step 1: Get the source code

git clone https://github.com/foks-proj/go-foks.git
cd go-foks

​
Step 2: Create a work directory

mkdir /path/to/workdir
This directory will hold FOKS binaries, configuration files, server keys, and scripts.

​
Step 3: Run config.bash

config.bash generates configuration files and scripts based on your deployment choices. 
cd /path/to/workdir
/path/to/go-foks/scripts/srv/config.bash \
    --network-mode prod \
    --run-mode systemd \
    --server-mode standalone \
    --base-hostname foks.yourdomain.com

​
Key options

OptionValuesDescription
--network-modeprod, dev, testHow the server connects to the network
--run-modesystemd, docker_compose, pm2How processes are managed
--server-modestandalone, hosting_platformDeployment topology
--base-hostnameyour domainThe DNS hostname all services advertise (becomes external_addr)
--db-byo(flag)Use an existing PostgreSQL instance instead of Docker
Read config.bash to understand all available options — it’s written to be readable documentation.

​
Output files

config.bash produces:
FileDescription
conf/foks.jsonnetMain FOKS config (Jsonnet format, shared among all services)
conf/local.pre.libsonnetGenerated local overrides (hostname, ports, DB credentials)
conf/local.post.libsonnetGenerated local overrides (encryption keys, etc.)
env.shEnvironment variables for the next step
scripts/build.bashThe build/setup script
Verify the generated config: 
jsonnet conf/foks.jsonnet   # requires the jsonnet tool

​
Step 4: Run build.bash

build.bash runs the setup steps one at a time: 
cd /path/to/workdir
./scripts/build.bash next    # run the next pending step
Run next repeatedly until setup completes. The sequence of steps:
  1. setup_tools — install required tools
  2. make_web_assets — build the admin web UI
  3. create_docker_db — create a PostgreSQL container (skipped if --db-byo)
  4. create_foks_user — create the database user
  5. init_db — initialize the database schema
  6. gen_probe_ca — generate the probe CA
  7. gen_cks_cas — generate chain key store CAs
  8. make_host_chain — generate the host’s signing chain and HostID
  9. issue_frontend_cert — TLS certificate for public-facing services
  10. issue_backend_cert — mTLS certificates for internal services
  11. issue_probe_cert — certificate for the probe service
  12. issue_beacon_cert — certificate for beacon registration
  13. init_merkle_tree — initialize the Merkle tree
  14. write_public_zone — write the zone file (service endpoints)
  15. make_invite_code — generate an initial invite code
  16. write_dbkeys — write database encryption keys
  17. make_systemd_units — generate systemd unit files
  18. install_systemd_units — install them
  19. start_systemd — start all services
  20. beacon_register — register this host with the global beacon
Read build.bash — it’s also written as readable documentation for the setup process.

​
Step 5: Verify

After setup, verify that all services are running: 
systemctl status foks-*     # for systemd
# or
docker compose ps           # for docker compose

​
DNS configuration

All FOKS services run on the same machine under the same hostname (--base-hostname), differentiated by port. You only need a single A record: 
foks.yourdomain.com   A   <your-server-ip>
The probe service runs on port 443 (the base port); the other services (reg, user, kv_store, merkle_query) run on consecutive ports above it. Clients discover these ports automatically via the probe service — no additional DNS setup is needed.

​
Next steps