Skip to content

Self-host Docent

For most users, we recommend starting with the public version of Docent. We also provide white-glove hosting support for larger organizations; please reach out if you're interested.

1. Clone the repo and configure .env

git clone https://github.com/TransluceAI/docent.git
cd docent
cp .env.template .env

You should now have a .env file at the project root. See here for details on how to fill it in.

Note

If you're self-hosting Docent anywhere other than localhost, make sure to set the frontend URL as a CORS origin; e.g., DOCENT_CORS_ORIGINS=http://domain:3001.

2. Start the backend server and frontend UI

Docker Compose is the easiest way to get started, but you may want a manual installation to support faster development loops (e.g., for hot reloading).

First ensure Docker Engine and Docker Compose are installed. Then run:

DOCENT_HOST=http://localhost DOCENT_SERVER_PORT=8889 DOCENT_WEB_PORT=3001 docker compose up --build

# Note that `sudo` strips environment variables, so you have to set them *inside* the command.
sudo DOCENT_HOST=http://localhost DOCENT_SERVER_PORT=8889 DOCENT_WEB_PORT=3001 docker compose up --build

Note

If you're not using localhost, make sure DOCENT_HOST is set to the correct domain. Ensure that it's prefixed correctly with http:// or https://.

Cold build + start should take a few minutes. Once finished, you can run

docker ps

sudo docker ps

to check that the four following containers are running: 

CONTAINER ID   IMAGE             COMMAND                  CREATED          STATUS          PORTS                                         NAMES
b8bba5b86251   docent-backend    "bash -c 'bash /app/…"   34 seconds ago   Up 33 seconds   0.0.0.0:8889->8889/tcp, [::]:8889->8889/tcp   docent_backend
0cfc73d80407   docent-frontend   "docent web --build …"   34 seconds ago   Up 33 seconds   0.0.0.0:3001->3001/tcp, [::]:3001->3001/tcp   docent_frontend
c80f4302db12   postgres:15       "docker-entrypoint.s…"   34 seconds ago   Up 33 seconds   0.0.0.0:5432->5432/tcp, [::]:5432->5432/tcp   docent_postgres
f9d86be37643   redis:alpine      "docker-entrypoint.s…"   34 seconds ago   Up 33 seconds   0.0.0.0:6379->6379/tcp, [::]:6379->6379/tcp   docent_redis

To shut Docent down, either press Ctrl+C in the terminal or run:

docker compose down

sudo docker compose down

Note

If you make changes to the codebase, you'll need to stop the containers, then rebuild by keeping the --build argument. If --build is omitted, your changes will not be reflected.

If you don't already have Postgres and Redis installed, you can start them with Docker:

docker compose -f docker-compose-db.yml up --build

sudo docker compose -f docker-compose-db.yml up --build

after which Postgres and Redis will be available at the addresses set in .env. To set up your own databases, visit the official docs for Postgres and Redis.

Then run:

uv sync --extra dev

pip install -e .[dev]

to install the core library, and

pre-commit install

to set up pre-commit hooks for development.

Before running the application, you need to set up your database with Alembic migrations. First create a PostgreSQL database that matches the name in your .env file. Then run

alembic upgrade head

to create all database tables. Now run

docent_core server --port 8889 --workers 4

docent_core server --port 8889 --reload

to start the API server,

docent_core worker --workers 4

to start the worker, which handles background work, and

docent_core web --build --port 3001 --backend-url http://localhost:8889

docent_core web --port 3001 --backend-url http://localhost:8889

to start the frontend. You may need to install Bun first.

Finally, try accessing the Docent UI at http://$DOCENT_HOST:$DOCENT_WEB_PORT.

3. Customize the Docent client

When creating Docent client objects, you'll need to specify custom server and frontend URLs:

import os
from docent import Docent

client = Docent(
    server_url="http://localhost:8889",    # or your own server URL
    frontend_url="http://localhost:3001",  # or your own frontend URL
    api_key=os.getenv("DOCENT_API_KEY"),
)

You're all set! Check out our quickstart to get started.