Install

This page gets the ricochet binary onto your machine. Pick one of three routes: a release archive, a .deb package for Debian or Ubuntu, or a build from source. You need PostgreSQL in every case; set it up next in Database setup.

Release assets

Each release on GitHub carries these files:

File	Contents
ricochet_1.1.0_linux_amd64.tar.gz	Linux x86-64 binary
ricochet_1.1.0_linux_arm64.tar.gz	Linux ARM64 binary
ricochet_1.1.0_darwin_amd64.tar.gz	macOS Intel binary
ricochet_1.1.0_darwin_arm64.tar.gz	macOS Apple silicon binary
ricochet_1.1.0_windows_amd64.zip	Windows x86-64 binary (ricochet.exe)
ricochet-server_1.1.0_amd64.deb	Debian/Ubuntu package, x86-64
ricochet-server_1.1.0_arm64.deb	Debian/Ubuntu package, ARM64
SHA256SUMS	SHA-256 checksum of every file above

Download URLs take the form https://github.com/stephanfeb/go-ricochet/releases/download/v1.1.0/<file>.

The binaries are statically linked (built with CGO_ENABLED=0), so they have no runtime dependencies.

Note

There is no published Docker image yet; one is planned. The repository’s examples/mailbox/docker/ setup builds a server image from source for the mailbox demo. It is a demo, not a production image. See The mailbox example.

From a release archive

Download the archive for your platform and the checksum file, verify, then unpack:

VERSION=1.1.0
ASSET=ricochet_${VERSION}_linux_amd64.tar.gz
BASE=https://github.com/stephanfeb/go-ricochet/releases/download/v${VERSION}

curl -LO "$BASE/$ASSET"
curl -LO "$BASE/SHA256SUMS"
sha256sum --check --ignore-missing SHA256SUMS

tar -xzf "$ASSET"
cd ricochet_${VERSION}_linux_amd64
./ricochet --version

On macOS, sha256sum is not installed by default. Check the one line you need with shasum:

grep "$ASSET" SHA256SUMS | shasum -a 256 -c -

Each archive unpacks to a directory named after the archive, holding:

• ricochet (or ricochet.exe on Windows): the server
• schema.sql: the PostgreSQL schema
• config.example.yaml: every config key with its default and an explanation
• README.md and LICENSE

--version prints ricochet 1.1.0.

To install system-wide, copy the binary somewhere on your PATH, for example /usr/local/bin/ricochet. The server reads /etc/ricochet/config.yaml automatically when that file exists, so config.example.yaml is a good starting point for it.

From the Debian package

The .deb is the most complete install on Debian and Ubuntu. It runs the server under supervisord as a dedicated user.

VERSION=1.1.0
BASE=https://github.com/stephanfeb/go-ricochet/releases/download/v${VERSION}

curl -LO "$BASE/ricochet-server_${VERSION}_amd64.deb"
curl -LO "$BASE/SHA256SUMS"
sha256sum --check --ignore-missing SHA256SUMS

sudo apt install ./ricochet-server_${VERSION}_amd64.deb

The package depends on supervisor and postgresql-client, which apt installs for you. It does not install the PostgreSQL server.

What the package installs

Path	What it is
/opt/ricochet/ricochet_server	The server binary
/opt/ricochet/run.sh	Startup wrapper: reads /etc/ricochet/env, starts the server with --production
/opt/ricochet/health_check.sh	Health check against the ops listener
/opt/ricochet/schema.sql	The PostgreSQL schema
/etc/ricochet/config.yaml	Config file, comments only as shipped (conffile)
/etc/ricochet/config.yaml.example	Every key, documented
/etc/ricochet/env.example	Template for the environment file
/etc/ricochet/env	Created from env.example on first install, mode 640, owner root:ricochet
/etc/supervisor/conf.d/ricochet.conf	supervisord program definition (conffile)
/var/lib/ricochet/	Working directory; the identity key lives in sf_storage/ under it
/var/log/ricochet/	stdout.log and stderr.log

The install also creates a ricochet system user. The package ships no systemd unit; supervisord runs the server. See Process supervision.

Finish the install

1. Edit /etc/ricochet/env. Set DB_PASSWORD and EXTERNAL_IP (the public address clients reach this host on). Set DB_SSLMODE=disable only if PostgreSQL runs on the same host or a private network you trust.

2. Create the database and load the schema. See Database setup.

3. Start the server:

   sudo supervisorctl start ricochet
   sudo supervisorctl status ricochet

run.sh passes these variables from /etc/ricochet/env to the server:

Variable	Default	Becomes
DB_PASSWORD	none, required	RICOCHET_PG_PASSWORD in the server’s environment
EXTERNAL_IP	empty	--external-addrs /ip4/$EXTERNAL_IP/udp/<port>/udx
LISTEN_PORT	unset (config or preset, 55223)	--port
DB_HOST	localhost	--pg-host
DB_PORT	5432	--pg-port
DB_NAME	ricochet	--pg-database
DB_USER	ricochet	--pg-username
DB_SSLMODE	require	--pg-sslmode

It also passes --data-dir /var/lib/ricochet/sf_storage. Flags override /etc/ricochet/config.yaml, so set these values in env, not in the config file.

To build the .deb yourself, run scripts/package-deb.sh on Linux (VERSION=1.1.0 ARCH=amd64), or ./build-deb.sh on macOS, which runs the same script inside Docker.

From source

You need Go 1.25.7 or later; this is the floor go.mod sets. An older go command downloads the right toolchain itself under the default GOTOOLCHAIN=auto.

git clone --branch v1.1.0 https://github.com/stephanfeb/go-ricochet.git
cd go-ricochet
go build -trimpath -ldflags "-X main.version=1.1.0" -o ricochet ./cmd/ricochet
./ricochet --version

Without the -ldflags setting, --version prints ricochet dev. The release builds use CGO_ENABLED=0 go build -trimpath -ldflags "-s -w -X main.version=<version>".

The load-testing tool is not in the release assets. Build it the same way:

go build -o ricochet-bench ./cmd/ricochet-bench

See Benchmarking.

Next

• Database setup
• First run & your peer ID