Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/SoftwareVerse/userverse/llms.txt

Use this file to discover all available pages before exploring further.

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": "no-reply@example.com",
        "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

VariableRequiredDescription
JSON_CONFIG_PATHYes (production)Absolute path to your JSON configuration file inside the container.
DATABASE_URLNoSQLAlchemy-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).
ENVNoRuntime 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.

Database setup

Create your PostgreSQL database and run Alembic migrations.

Configuration

Full reference for every field in the JSON config file.

Build docs developers (and LLMs) love

Get started for freeTalk to us