Skip to main content

Install Riviamigo

This is the quick, self-hosted path—not the developer environment. It pulls published images through the standard Compose stack in compose/.

Before you start​

You will need Docker Compose v2, Git, and a trusted host. Read the prerequisites first, especially if the instance will be reachable away from home.

Bring up Riviamigo​

  1. Clone the repository and enter it:

    git clone https://github.com/bballdavis/Riviamigo.git
    cd Riviamigo

  2. Create a .env file. The compact Compose template contains only the values a standard install needs; set each placeholder as described in configuration. Do not commit this file.

    cp compose/.env.example .env

  3. Replace every CHANGE_ME value before starting the stack. In particular, set a random 32-byte-or-longer first-owner proof in RIVIAMIGO_SETUP_TOKEN (or configure RIVIAMIGO_SETUP_TOKEN_FILE), strong database and Redis passwords, and your exact public HTTPS origin.

  4. Start the stack:

    docker compose --env-file .env -f compose/docker-compose.yml up -d

  5. Before exposing the service, put an authenticated HTTPS gateway and host firewall rule in front of the origin, open the gateway address, and create the first account with the configured proof. The first account becomes the instance owner and can connect the first Rivian. Remove or rotate the bootstrap proof after setup, then recreate the app with docker compose --env-file .env -f compose/docker-compose.yml up -d. Use a password with at least 12 characters; the setup screen shows the live requirement as you type.

The standard stack defaults to production mode and publishes port 8080 only using the normal Docker host publication. Set RIVIAMIGO_HOST_BIND_ADDRESS when a specific host interface is required, and follow secure deployment before making it available outside your local network.

Using Synology DSM? Follow the dedicated Synology installation guide. The DSM guide includes the setup-token template, first-boot delay, and shared folder ACL checks required for a fresh install.

Copy the standard Compose file​

This is the exact production Compose file from the repository, included at build time so the documentation stays synchronized with the installation source. Copy it into compose/docker-compose.yml if you are working from a downloaded documentation bundle, or use the linked source file directly: compose/docker-compose.yml.

services:
  riviamigo:
    image: ${RIVIAMIGO_IMAGE:-${RIVIAMIGO_IMAGE_REGISTRY:-ghcr.io/bballdavis}/riviamigo:${IMAGE_TAG:-latest}}
    restart: unless-stopped
    env_file:
      - ${RIVIAMIGO_ENV_FILE:-../.env}
    environment:
      # LAN-only escape hatch for browser clients without HTTPS. Keep false unless
      # the documented private-network requirements are intentionally met.
      ALLOW_INSECURE_LAN_HTTP_AUTH: ${ALLOW_INSECURE_LAN_HTTP_AUTH:-false}
    depends_on:
      timescaledb:
        condition: service_healthy
      redis:
        condition: service_healthy
    ports:
      - "${RIVIAMIGO_HOST_BIND_ADDRESS:-0.0.0.0}:${RIVIAMIGO_ORIGIN_PORT:-8080}:8080"
    user: "1001:1001"
    read_only: true
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges:true
    tmpfs:
      - /tmp:rw,nosuid,nodev,size=128m
    networks:
      - internal
      - proxy
    healthcheck:
      test: ['CMD', 'curl', '-f', 'http://localhost:8080/health']
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 120s
    volumes:
      - ${RIVIAMIGO_BACKUPS_SOURCE:-${RIVIAMIGO_DATA_DIR:-../data}/backups}:/backups
      - ${RIVIAMIGO_CACHE_SOURCE:-${RIVIAMIGO_DATA_DIR:-../data}/cache}:/data/cache

  timescaledb:
    image: timescale/timescaledb:2.28.3-pg18@sha256:2c718e700b1c75b93488085596f2254c991c3aa29584fc282ebbe62fd8335791
    restart: unless-stopped
    environment:
      POSTGRES_DB: riviamigo
      POSTGRES_USER: ${POSTGRES_USER:-riviamigo}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env}
      PGDATA: /db
    volumes:
      - ${RIVIAMIGO_DB_SOURCE:-${RIVIAMIGO_DATA_DIR:-../data}/db}:/db
    networks:
      - internal
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U ${POSTGRES_USER:-riviamigo} -d riviamigo']
      interval: 10s
      timeout: 5s
      retries: 30
      start_period: 300s

  redis:
    image: redis:8.8.0-alpine@sha256:9d317178eceac8454a2284a9e6df2466b93c745529947f0cd42a0fa9609d7005
    restart: unless-stopped
    command:
      [
        'redis-server',
        '--requirepass',
        '${REDIS_PASSWORD:?Set REDIS_PASSWORD in .env}',
        '--appendonly',
        'yes',
      ]
    environment:
      REDIS_PASSWORD: ${REDIS_PASSWORD:?Set REDIS_PASSWORD in .env}
    volumes:
      - ${RIVIAMIGO_REDIS_SOURCE:-${RIVIAMIGO_DATA_DIR:-../data}/redis}:/data
    networks:
      - internal
    healthcheck:
      test: ['CMD-SHELL', 'redis-cli --no-auth-warning -a "$$REDIS_PASSWORD" ping']
      interval: 10s
      timeout: 5s
      retries: 30

volumes:
  riviamigo-db:
  riviamigo-redis:
  riviamigo-backups:
  riviamigo-cache:

networks:
  internal:
    driver: bridge
    internal: true
  proxy:
    driver: bridge

Other Compose variants are available when you need them:

Next steps​