Docker deployment

Build and run Userverse as a Docker container. This page covers the Dockerfile, required environment variables, and a complete docker run example.

Userverse ships with a Dockerfile that packages the application using uv for dependency management. The image exposes port 8500 and expects a JSON config file to be mounted or baked in at startup.

You must have a running PostgreSQL database before starting the container. See the database setup page for instructions.

Dockerfile

The repository’s Dockerfile is reproduced below for reference:

FROM python:3.12
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/

WORKDIR /code

COPY ./pyproject.toml /code/pyproject.toml

RUN uv sync

COPY ./app /code/app

COPY ./sample-config.json /code/sample-config.json

EXPOSE 8500

# Better CMD that directly runs your application
CMD ["uv", "run", "-m", "app.main", "--port", "8500", "--host", "0.0.0.0", "--env", "production" \
    , "--json_config_path", "/code/sample-config.json"]

The default CMD passes --json_config_path /code/sample-config.json directly to the application entry point. You can override this at runtime by supplying your own config file path (see running the container below).

Build, configure, and run

1. Build the image

   Clone the repository and build the Docker image from the project root:

   git clone https://github.com/SoftwareVerse/userverse.git
   cd userverse
   docker build -t userverse:latest .
   
2. Prepare your config file

   Copy sample-config.json and edit it with your production values — database credentials, JWT secret, SMTP settings, and allowed CORS origins. See the configuration reference for all available fields.

   cp sample-config.json my-config.json
   

   Your config file must include a database block so Userverse can reach PostgreSQL:

   {
       "server_url": "https://api.example.com",
       "name": "Userverse",
       "cor_origins": {
           "allowed": ["https://app.example.com"],
           "blocked": []
       },
       "jwt": {
           "SECRET": "replace-with-a-long-random-secret",
           "ALGORITHM": "HS256",
           "TIMEOUT": 30,
           "REFRESH_TIMEOUT": 60
       },
       "database": {
           "HOST": "db.example.com",
           "PORT": 5432,
           "USERNAME": "userverse",
           "PASSWORD": "strongpassword",
           "NAME": "userverse",
           "TYPE": "postgresql"
       },
       "email": {
           "HOST": "smtp.example.com",
           "PORT": 587,
           "USERNAME": "[e-mail]",
           "PASSWORD": "emailpassword"
       }
   }
   
3. Run the container

   Mount your config file into the container and point JSON_CONFIG_PATH at it:

   docker run -d \
     --name userverse \
     -p 8500:8500 \
     -e JSON_CONFIG_PATH=/config/my-config.json \
     -v "$(pwd)/my-config.json:/config/my-config.json:ro" \
     userverse:latest \
     uv run -m app.main \
       --port 8500 \
       --host 0.0.0.0 \
       --env production \
       --json_config_path /config/my-config.json
   

   The API will be available at http://localhost:8500.

Environment variables

Variable	Required	Description
JSON_CONFIG_PATH	Yes (production)	Absolute path to your JSON configuration file inside the container.
DATABASE_URL	No	SQLAlchemy-compatible database URL. Used by DatabaseSessionManager as a fallback when no database block is present in the config file (e.g., postgresql://user:pass@host:5432/dbname).
ENV	No	Runtime environment name passed to the server. Set to production in the CMD.

Pass DATABASE_URL as an environment variable when you prefer to keep database credentials out of the config file entirely. DatabaseSessionManager reads it automatically if no database_url key is present in the loaded config.

Related pages

Database setup

Create your PostgreSQL database and run Alembic migrations.

Configuration

Full reference for every field in the JSON config file.