Docker

Sairo ships as a single Docker image. You can run it directly with docker run or use Docker Compose for a more reproducible setup.

Docker run

The quickest way to start Sairo:

docker run -d --name sairo -p 8000:8000 \
  -e S3_ENDPOINT=https://your-s3-endpoint.com \
  -e S3_ACCESS_KEY=your-access-key \
  -e S3_SECRET_KEY=your-secret-key \
  -e ADMIN_PASS=choose-a-strong-password \
  -e JWT_SECRET=$(openssl rand -hex 32) \
  -v sairo-data:/data \
  stephenjr002/sairo:latest

Docker Compose

For production or team environments, Docker Compose keeps your configuration in version control.

1. Create your environment file

cp .env.example .env

Edit .env and fill in your S3 credentials and admin password. See the Configuration reference for all available variables.

2. Start the service

docker compose up -d

Compose file reference

services:
  sairo:
    build: .
    ports:
      - "8000:8000"
    env_file: .env
    volumes:
      - sairo-data:/data
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/healthz')"]
      interval: 30s
      timeout: 5s
      retries: 3

volumes:
  sairo-data:

Image tags

Every push to main and every version tag produces a Docker image. The following tags are available on Docker Hub:

Tag	When pushed	Use case
:latest	Every push to main	Development, always the newest build
:X.Y.Z (e.g. :2.1.0)	On vX.Y.Z release	Production — pin to an exact release
:X.Y (e.g. :2.1)	On vX.Y.Z release	Track patch updates within a minor version
:sha-abc1234	Every push + release	Pinpoint a specific commit

All images are built for linux/amd64 and linux/arm64.

Tip

Use :latest for development and testing. For production, pin to a specific version like :2.1.0 so upgrades are intentional.

Volume mount

The /data directory inside the container stores all SQLite database files (one per bucket). Mounting a named volume or host path to /data ensures your index survives container restarts.

Container path	Purpose
/data	SQLite databases (per-bucket .db files, WAL journals)

If you lose the /data volume, Sairo will simply rebuild the index from S3 on the next startup. No data is lost, but the initial crawl will take time depending on how many objects you have.

Health check

Sairo exposes a health check endpoint:

GET /healthz

Returns 200 OK when the service is ready. Use this in Docker health checks, load balancer probes, or monitoring systems.

curl -f http://localhost:8000/healthz

HTTP vs HTTPS

Sairo’s authentication relies on cookies with the Secure flag enabled by default. This means cookies are only transmitted over HTTPS connections.

Caution

If you access Sairo over plain HTTP (for example, during local development or behind a reverse proxy that terminates TLS), you must set:

SECURE_COOKIE=false

Without this, authentication cookies will silently fail — you will be able to log in but every subsequent request will appear unauthenticated.

Behind TLS proxy (default)

# SECURE_COOKIE defaults to true -- no change needed
-e S3_ENDPOINT=https://s3.example.com

Plain HTTP (local/dev)

-e SECURE_COOKIE=false

Upgrading

To upgrade Sairo to a new version:

docker run

docker pull stephenjr002/sairo:latest
docker stop sairo
docker rm sairo
# Re-run the original docker run command

Docker Compose

docker compose pull
docker compose up -d

Your SQLite index in the sairo-data volume is preserved across upgrades. Sairo handles any necessary schema migrations automatically on startup.