First run & your peer ID

This page starts the server for the first time and gets you the one thing every client needs: the server’s multiaddr, ending in its peer ID.

Before you start

• The ricochet binary. See Install.
• A PostgreSQL database with schema.sql loaded. See Database setup.
• UDP port 55223 open to your clients, if they are not on the same machine.

Start the server

For a local trial against a database on the same machine:

export RICOCHET_PG_PASSWORD='change-me'
./ricochet --development \
  --pg-host localhost \
  --pg-database ricochet \
  --pg-username ricochet \
  --data-dir ./sf_storage

--development turns TLS to PostgreSQL off, caps connections at 100 and logs at DEBUG. For a real deployment use --production, which keeps TLS to the database on. See Presets.

If /etc/ricochet/config.yaml exists, the server loads it on top of the preset and prints Loaded config from /etc/ricochet/config.yaml. Pass --config <path> to use another file.

On the .deb install, supervisorctl start ricochet does all of this through /opt/ricochet/run.sh, with the production preset. Its output goes to /var/log/ricochet/stdout.log.

Find the peer ID

When startup succeeds, the server prints:

Ricochet server 1.1.0 running. Peer ID: 12D3KooW...

The peer ID also appears in the log lines loaded identity and server started (field peer_id). The server started line also lists the addresses the host listens on (field addrs).

The peer ID is derived from the server’s Ed25519 identity key. It stays the same across restarts as long as the key does. On first start the server generates the key and writes it to <data-dir>/peer_identity.key, mode 600. With no --data-dir, the data directory is ./sf_storage, relative to the working directory.

Caution

Back up peer_identity.key. If you lose it, the server comes back with a new peer ID, and every client and peer configured with the old one stops finding it. See Identity keys.

The address clients use

A client needs the server’s full multiaddr: transport address plus peer ID.

/ip4/203.0.113.10/udp/55223/udx/p2p/12D3KooW...

• 203.0.113.10 is the public address clients reach the host on.
• 55223 is the listen port, the default.
• udx is the transport. It is the only one the server runs; see Transport.
• The /p2p/... part is the peer ID from the startup line.

For a local test, use /ip4/127.0.0.1/udp/55223/udx/p2p/<peer-id>. How a client takes this address is covered in Creating a client.

Listen and external addresses

By default the server listens on /ip4/0.0.0.0/udp/55223/udx: every IPv4 interface, UDP port 55223.

/etc/ricochet/config.yaml

server:
  port: 55223
  listen_addresses:
    - /ip4/0.0.0.0/udp/55223/udx
  external_addresses:
    - /ip4/203.0.113.10/udp/55223/udx

--port rewrites the port in every listen address. In the YAML file, server.port only rewrites the default listen address; if you also set listen_addresses, put the port in those addresses yourself.

Set external_addresses (or --external-addrs, comma-separated) to the public address clients use. Without it the server advertises only the addresses on its own interfaces. Behind NAT or on a cloud VM those are private, and a client that loses its connection can no longer find the server’s address. On the .deb install, set EXTERNAL_IP in /etc/ricochet/env and run.sh builds the flag for you. A NAT setup has more options; see NAT traversal & relay.

Note

On Linux, listening on both /ip6/::/udp/55223/udx and /ip4/0.0.0.0/udp/55223/udx fails: the IPv6 socket claims both address families by default. Use one.

Check it works

1. The process printed the Peer ID line and keeps running.

2. The ops listener answers on loopback:

   curl -s http://127.0.0.1:9090/healthz
   curl -s http://127.0.0.1:9090/readyz

   /readyz returns 200 with "ready":true once the database is reachable. See Health & readiness.

3. A request from a client produces one log line with msg=request, carrying protocol, op, status, peer and duration. To generate load without writing a client, see Benchmarking.

Stop the server

Send SIGINT (Ctrl+C) or SIGTERM. The server stops admitting requests, lets the ones in flight finish, then closes the network and the database pool. A second signal forces an immediate exit. See Upgrades & draining.

Troubleshooting

• failed to load config file ...: the file is unreadable, invalid YAML, or holds an unknown key. The message names the key, for example field logging not found. There is no logging: section; delete it.
• invalid config: ...: a value failed validation, for example enable_authentication with no trusted_peers. The message says which.
• choose one of --development, --production, --high-capacity: you passed more than one preset.
• Startup fails at initialize p2p: usually the UDP port is in use or a listen address is malformed.
• start ops api: listen on 127.0.0.1:9090 ...: something else holds port 9090. Change ops.port.