Updating

Updating takes two commands. Your server identity, uploaded files, and database are all stored in Docker volumes and survive image updates.

Docker Compose

# Pull the latest image
docker compose -f docker-compose.server.yml pull

# Restart with the new version
docker compose -f docker-compose.server.yml up -d

The running container is replaced with the new image. Downtime is typically under 5 seconds.

Plain Docker

# Pull the new image
docker pull ghcr.io/realm-app/realm-server:latest

# Stop and remove the old container
docker stop realm-server
docker rm realm-server

# Start a new container with the same flags
docker run -d \
  --name realm-server \
  -p 5000:5000 \
  -p 40000-49999:40000-49999/udp \
  -e REALM_IDENTITY_NAME="My Server" \
  -e REALM_STORAGE_MONGO_URL="mongodb://your-mongo-host:27017/realm" \
  -e REALM_WEBRTC_ANNOUNCED_IP="YOUR_SERVER_PUBLIC_IP" \
  -v server-data:/data \
  ghcr.io/realm-app/realm-server:latest

What's preserved

Data	Where it lives	Preserved?
Server identity (ID + keys)	`server-data` volume, `/data/server-identity.json`	Yes
Uploaded attachments	`server-data` volume, `/data/uploads/`	Yes
Channels and messages	`mongo-data` volume	Yes
Config	`config.json` mount or env vars	Yes (you manage this)

Pinning to a specific version

To use a specific release instead of latest:

# In docker-compose.server.yml
image: ghcr.io/realm-app/realm-server:0.3.0

Check available tags in the container registry at ghcr.io/realm-app/realm-server.

Version compatibility

Realm enforces a version policy. If you see "Version not allowed" in the logs after updating, your version has been blocked. Pull the latest image and restart to get a supported version.

Automated updates with Watchtower

Watchtower can pull and restart containers automatically when new images are published:

docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower \
  --interval 3600 \
  realm-server

This polls for new images every hour. Consider pinning to a minor version tag (e.g. 0.3) rather than latest if you want to avoid unintended major updates.