Run the development environment

The goal is to run VideoQ on your computer and log in. Start with Docker Compose managing the API, database, and video processing.

For documentation-only changes, go to Update the documentation. You do not need to start the app.

Prerequisites

Requirement	Purpose
Git and repository access	Get the source code
Docker and Docker Compose	Run the database, API, video processing, and related services
Node.js 22.12 or later and npm	Install dependencies and configure a local account
An OpenAI API key for development	Transcription, search data generation, and AI answers

The video processing and AI answers in this guide incur external API usage charges. Use a development key and a short test video. A separate SearchAPI key is needed only for YouTube imports.

1. Get the code and configuration

git clone https://github.com/yukiharada1228/videoq.git
cd videoq
cp -n .env.example .env
npm ci

Run subsequent commands from the repository root, videoq/, unless stated otherwise. Skip cloning if you already have a working copy.

2. Configure AI services for development

Edit the matching entries in .env to use these values. Set OPENAI_API_KEY to your own development key.

OPENAI_API_KEY=your-development-key
OPENAI_BASE_URL=https://api.openai.com/v1
LLM_MODEL=gpt-4o-mini
WHISPER_BACKEND=openai
EMBEDDING_PROVIDER=openai
EMBEDDING_MODEL=text-embedding-3-small
EMBEDDING_VECTOR_SIZE=1536

Set EMBEDDING_VECTOR_SIZE to 1536. The current .env.example uses 1024, but the database schema defines 1536 dimensions. Search will not work if the API and video processing use different dimensions. See embeddings in the glossary.

Generate two development secrets:

openssl rand -base64 48
openssl rand -base64 32 | tr '+/' '-_' | tr -d '='

Set .env's AUTH_JWT_SECRET to the first output and USER_SECRET_ENCRYPTION_KEY to the second.

AUTH_JWT_SECRET is a compatibility setting used by the current Compose startup script. Browser authentication uses Better Auth cookie sessions. When running the API directly on the host, use BETTER_AUTH_SECRET. See authentication for the distinction.

3. Start the services

docker compose up --build -d
docker compose ps -a

The first start takes time to download and build images.

• Continue when services such as postgres, api, worker, web, and gateway are running.
• migrate and minio-init stop after initialization. Exit code 0 means they completed successfully.
• If a service fails, inspect it with docker compose logs --tail=100 migrate api worker.

curl -fsS http://localhost/health
curl -fsS http://localhost/ready

/health checks that the API responds; /ready also checks DB connectivity. A successful /ready response looks like this:

{"data":{"status":"ready","db":"ok"}}

4. Create an account and log in

1. Create a user on the local signup screen.
2. In a local environment without email configured, activate the account and grant administrator access with the following command. Replace your-username with the username or email address you registered.

npm run user:superuser --workspace @videoq/api -- your-username

3. Log in on the login screen.

This promotion procedure is for your own local development database. The default connection is 127.0.0.1:55432 on the host. If you have already set DATABASE_URL, check its target before running the command.

5. Edit the frontend

The default http://localhost serves a built frontend. Add the Vite development server to see changes immediately:

docker compose --profile dev up --build -d web-dev

Open http://localhost:3000 during development. This is a separate entry point from the static frontend at http://localhost.

Stop and restart

docker compose stop
docker compose up -d

stop preserves the local database and videos. After changing .env, recreate the affected services to reload their settings:

docker compose up -d --force-recreate api worker

Starting the API through Docker generates apps/api/.dev.vars. Manual edits to this file are overwritten at the next start, so edit .env for Compose setups. The startup script forwards only a defined subset of settings.

Read next: Add a video and ask questions. If startup fails, see Troubleshooting.