Getting Started

---

What you will find on this page 🦉

• Overview - everything at a glance
• Installation - all you need to know to get ExplAIner running locally
• Configuration - all environment variables explained

---

Overview

For an overview of the technologies used, see the Tech Stack.

For extending the project, see the Contributor Guide.

	local dev	local prd
Purpose	Local development	Mirror production locally
Client port	3000	4000
Server port	3001	4001
DB port	5432	5433
Script	docker-compose.dev.yml	docker-compose.prd.yml

---

Installation

Since Docker is amazing, ExplAIner runs entirely in Docker. Owlbert 🦉 created two local Docker environments - one dev environment with hot-reload for local development, and one prd environment to verify locally everything works before deploying to production. Everything is set-up, you will only need to start one docker-compose file to start either the dev or prd environment - piece of 🎂! Here is a simple step by step guide:

Prerequisites: Install Docker Desktop and verify installation:

docker version
docker compose version

Running both local environments (dev & prd) in parallel requires about 1 GB of RAM.

Steps:

1. Clone the repo:

   git clone https://github.com/martin-stierlen/ExplAIner.git
   

2. Navigate into the project:

   cd ExplAIner/

3. Configure env files

   • Create file .env.dev in root folder
   • Create file .env.prd in root folder
   • Copy&Paste the content of .env.dev.example into .env.dev and add all required variables
   • Copy&Paste the content of .env.prd.example into .env.prd and add all required variables

   Note: ExplAIner uses Anthropic as its LLM provider, so you will need your own Anthropic API key. Getting one is quick and straightforward - simply follow the steps in the Anthropic documentation.

4. Start/Stop the dev environment for local development:

   docker compose -f docker-compose.dev.yml --env-file .env.dev up --build
   docker compose -f docker-compose.dev.yml down

   Start/Stop the prd environment for verify everything works before deploying:

   docker compose -f docker-compose.prd.yml --env-file .env.prd up --build
   docker compose -f docker-compose.prd.yml down

5. (Optional, but recommended!) Setup Aliases

   Add the following to your ~/.zshrc file to avoid typing the full command every time:

   alias dc-dev="docker compose -f docker-compose.dev.yml --env-file .env.dev"
   alias dc-prd="docker compose -f docker-compose.prd.yml --env-file .env.prd"

   Now you can simply use:

   dc-dev up --build   # start dev with fresh build
   dc-dev up           # start dev
   dc-dev down         # stop dev

---

Configuration

All environment variables are configured via two env files at the project root:

• .env.dev for the dev environment and
• .env.prd for the prd environment

Both files share the same structure:

Server

Variable	Description	Example
SERVER_PORT	Server port	3001
DB_USER	Postgres username	your-db-username
DB_PASSWORD	Postgres password	your-db-password
DB_NAME	Database name	your-db-name
ANTHROPIC_API_KEY	Secret - Anthropic API key	sk-ant-...
ANTHROPIC_MODEL	Claude model identifier	claude-sonnet-4-5-20250929

Client

Variable	Description	Example
CLIENT_PORT	Client port	3000
CLIENT_URL	Client origin (used for CORS)	http://localhost:3000
NEXT_PUBLIC_API_URL	Backend base URL (baked into Next.js build)	http://localhost:3001

---