Getting Started

Recto is a self-hosted journal backend that runs with Docker Compose. This guide will have you journaling through your AI assistant in minutes.

Prerequisites

Docker and Docker Compose
An AI assistant that supports MCP (Claude Desktop, Claude Code, Cursor, etc.)

Quick Start

1. Clone and configure

git clone https://github.com/KristijanS99/recto.git
cd recto
cp .env.example .env

Edit .env and set these required values:

Variable	Description
`RECTO_API_KEY`	Secret key for API auth (min 32 characters)
`RECTO_WEB_PASSWORD_HASH`	Bcrypt hash for web UI login (see below)

Generate the password hash:

docker run --rm caddy:2-alpine caddy hash-password --plaintext 'your-password'

2. Start the stack

docker compose up -d

This starts four services:

Container	Purpose	Port
`recto-db`	PostgreSQL + pgvector	5432
`recto-api`	REST API	3000
`recto-mcp`	MCP server (AI assistant interface)	3001
`recto-proxy`	Caddy reverse proxy (TLS, auth, routing)	80 / 443

A temporary recto-web container builds the dashboard files and exits — Caddy serves them directly.

3. Verify it works

curl http://localhost:3000/health
curl http://localhost:3001/health

Both should return {"status":"ok"}.

Open https://localhost to access the web dashboard. Your browser will warn about the self-signed certificate on localhost — accept it and log in with your username and password.

Next Steps

Configure — Set up AI providers, API keys, and embedding models
Connect your AI assistant — Add Recto as an MCP server
Deploy — Set up for production or remote access
Start journaling — Talk to your AI assistant naturally. It handles the rest.