Quickstart: Run Recall Locally

Setup Steps

Clone the stack repository

git clone https://github.com/brainz-lab/stack.git
cd stack

Create your environment file

cp .env.example .env

The defaults work for local development. No changes needed.

Generate secret keys

Run the setup script to generate all required keys:

./scripts/setup.sh

Start the services

This starts Recall along with its dependencies (PostgreSQL, Redis):

docker-compose up -d recall timescaledb redis traefik

Tip: To run the full stack (all services), use ./scripts/start.sh

Add hosts entry (optional but recommended)

For subdomain routing, add to /etc/hosts:

127.0.0.1 recall.localhost

✓

Access Recall

Open your browser:

http://recall.localhost ↗ or http://localhost:3001 ↗

Send Your First Log

Once Recall is running, send a test log from your Rails app.

1. Add the SDK to your Gemfile

gem 'brainzlab'

2. Configure the initializer

# config/initializers/brainzlab.rb
BrainzLab.configure do |config|
  config.recall_url = "http://recall.localhost"
  config.recall_api_key = "your_ingest_key_from_env"
end

3. Send a log

# Anywhere in your Rails app
BrainzLab::Recall.info("User signed up", user_id: 123, plan: "pro")
BrainzLab::Recall.warn("Rate limit approaching", current: 95, max: 100)
BrainzLab::Recall.error("Payment failed", order_id: 456, reason: "card_declined")

Find your ingest key: Check the RECALL_INGEST_KEY in your .env file after running setup.

Useful Commands

View logs

docker-compose logs -f recall

Stream Recall's application logs in real-time.

Stop services

docker-compose down

Stop and remove all running containers.

Restart Recall

docker-compose restart recall

Restart just the Recall service.

Health check

curl http://localhost:3001/up

Verify Recall is healthy and responding.

Reset everything

./scripts/reset.sh

Stop services, remove volumes, start fresh.

Troubleshooting

Port 3001 already in use

Something else is using the port. Find and stop it:

lsof -i :3001
kill -9 <PID>

Database connection errors

Make sure TimescaleDB is healthy:

docker-compose ps timescaledb
docker-compose logs timescaledb

Service won't start

Check if the container has errors:

docker-compose logs recall

Run Recall Locally

Prerequisites