Running the Archipelago Release

Archipelago is an Elixir/OTP umbrella application, not a pharos binary. A realm runs as the archipelago release with PostgreSQL behind it. SSH is the primary playable transport; WebSocket is also supervised and enabled by default.

The repository is still a developer preview. There is no published one-command installer, hosted realm directory, or stable production migration guide.

Requirements

Elixir 1.18 or newer and OTP 27 or newer
PostgreSQL with pgvector
Rust and a C/C++ toolchain for the Rhai and QUIC NIFs
ssh-keygen on the runtime host
Docker Compose if you use the supplied local stack

Local source run

git clone https://github.com/thinkingsage/archipelago.git
cd archipelago
cp .env.example .env
mix setup
mix run --no-halt

mix setup fetches dependencies, creates the database, runs migrations, and seeds the showcase realm. The SSH listener defaults to port 2222; WebSocket defaults to 8080.

ssh -p 2222 traveler@localhost

A new public key enters registration on first connection. The supplied code also supports password registration by connecting with the desired username and the temporary password new.

Docker development stack

docker compose up --build

The compose file starts PostgreSQL, PgBouncer, Jaeger, and a source-mounted realm node. SSH is published on 22022; Jaeger is available on 16686.

ssh -p 22022 traveler@localhost

The compose configuration is for development. Its credentials are deliberately local, source is mounted into the container, and the realm runs under MIX_ENV=dev.

Production image

The root Dockerfile builds a multi-stage OTP release:

docker build -t archipelago:0.1.0 .
docker run --rm \
  -e DATABASE_URL='ecto://USER:PASS@HOST/DB' \
  -e OTLP_ENDPOINT='http://collector:4317' \
  -e ARCHIPELAGO_SSH_PORT=2222 \
  -e ARCHIPELAGO_WS_PORT=8080 \
  -p 2222:2222 \
  -p 8080:8080 \
  archipelago:0.1.0

Set ARCHIPELAGO_WS_ENABLED=false to disable WebSocket. POOL_SIZE defaults to 20 in production. The Ecto configuration assumes PgBouncer transaction mode and unnamed prepared statements.

Realm data

World state is event-sourced in PostgreSQL. Realm prose may be authored as Markdown under content/<realm>/ and seeded with mix content.seed; live build-mode changes become events. The repository’s archipelago.toml supplies realm presentation and budget settings, but the application does not yet expose a general --realm <directory> launcher.

Back up the database and the realm key material used by RealmKeypair. The old advice to copy a local store/ directory is incorrect: there is no file-backed event store.

The backup modules include pg_dump, WAL-archive, scheduler, and integrity-validation primitives. Wire them to the deployment environment and verify restore before treating them as an operational backup system.