Skip to content

Install with Podman quadlets

Use the quadlets when you run Podman with systemd instead of Docker Compose. They are in the quadlets/ folder of rag-docker 1.1.0 and run the same services as the compose file.

Prerequisites

  • Podman with quadlet support and systemd user services on the deployment host
  • An inference provider and API-key tooling as described in Install with Docker Compose

Configure

  1. Create the environment file as described in Install with Docker Compose, for example as /opt/rag/rag.env.

    No variable expansion

    Podman doesn't expand ${…} references in environment files. Write ConnectionStrings__DefaultConnection with the literal database name, user and password instead of the ${POSTGRES_…} references from example.env.

  2. Fill in the placeholders in the unit files:

    Unit What to set
    api-gateway, dlq-consumer, ingestion, rag-database-migrations, valkey, web-gateway EnvironmentFile=: replace REPLACE_ME_WITH_PATH_TO_ENV_FILE with the absolute path of your environment file
    gateway-database Environment=POSTGRES_PASSWORD/USER/DB: the POSTGRES_* values of your environment file
    rag-database Environment=POSTGRES_PASSWORD/USER/DB: the DB_PASSWORD, DB_USER and DB_NAME values
    rabbitmq Environment=RABBITMQ_DEFAULT_PASS/USER: the MB_PASSWORD and MB_USER values
    web-gateway-migrations Environment=ConnectionStrings__DefaultConnection=: the full connection string with literal values
    web-gateway PublishPort=8000:8080: change the host port if needed
  3. api-gateway, ingestion and dlq-consumer share the host folder /opt/rag-system/temp-uploads for uploaded files. Create it, or change the Volume= lines of all three units to another path. The container path must match TEMP_UPLOAD_DIR (default /app/temp_data).

  4. Copy the units and reload systemd:

    cp quadlets/*.container quadlets/*.volume quadlets/*.network ~/.config/containers/systemd/
    systemctl --user daemon-reload
    

Start

Start the dependencies first, then the services:

systemctl --user start rag-database rabbitmq
systemctl --user start rag-database-migrations
systemctl --user start web-gateway api-gateway ingestion dlq-consumer

web-gateway requires gateway-database, valkey and web-gateway-migrations, so systemd starts them first. The database and RabbitMQ units report ready only once their health checks pass. web-gateway-migrations is a one-shot unit: it runs on every start of web-gateway, applies pending migrations, and exits.

All units are installed into default.target, so they start with the user's systemd instance. For them to start at boot without a login session, enable lingering for the user: loginctl enable-linger <user>.

Check the installation with curl http://localhost:8000/version, as described in Install with Docker Compose. Then create a tenant and an API key.

Keep your values when you update

The quadlets carry your local values (env file path, credentials, port). When you replace them with the files of a newer release, apply your values again. The release notes list which lines changed.