Cerebro

Cerebro is a Rust backend for a newsletter service, built while working through Zero To Production In Rust. The project is intentionally developed in public: the codebase is still evolving, and each stage adds another production-oriented backend capability.

Current Scope

The application currently exposes:

• GET /health_check for service health checks
• POST /subscriptions for accepting newsletter subscription form data

Subscriptions are persisted in PostgreSQL via SQLx. The service uses Actix Web, Tokio, structured tracing, database migrations and environment-aware configuration.

Tech Stack

• Rust 2024 edition
• Actix Web
• Tokio
• PostgreSQL
• SQLx
• Docker for local Postgres
• tracing, tracing-subscriber and tracing-actix-web

Prerequisites

Install:

• Rust and Cargo
• Docker
• psql
• sqlx-cli

Install SQLx CLI with Postgres support:

cargo install sqlx-cli --no-default-features --features postgres,rustls

Configuration

Runtime configuration is stored in configuration.yaml.

For SQLx compile-time query checking, set DATABASE_URL. You can start from the example file:

cp .env.example .env

The default local database URL is:

postgres://postgres:password000@localhost:5432/newsletter

Do not commit .env; it is intentionally ignored.

Local Development

Start Postgres and run migrations:

./scripts/init_db.sh

If Postgres is already running and you only want to create/migrate the database:

SKIP_DOCKER=true ./scripts/init_db.sh

You can also start the database manually with Docker:

docker run \
  --name cerebro-postgres \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=password000 \
  -e POSTGRES_DB=newsletter \
  -p 5432:5432 \
  -v cerebro-postgres-data:/var/lib/postgresql/data \
  -d postgres \
  postgres -N 1000

If you use the manual Docker command, run migrations afterwards:

SKIP_DOCKER=true ./scripts/init_db.sh

Later you can stop and restart the same database container:

docker stop cerebro-postgres
docker start cerebro-postgres

Run the application:

cargo run

By default the server listens on:

127.0.0.1:8000

Check the health endpoint:

curl http://127.0.0.1:8000/health_check

Create a subscription:

curl -i -X POST http://127.0.0.1:8000/subscriptions \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "name=app%20tester&email=app_tester%40mail.com"

Tests

Run the test suite with a live local Postgres instance available:

DATABASE_URL=postgres://postgres:password000@localhost:5432/newsletter cargo test

Or export DATABASE_URL once for the current shell session:

export DATABASE_URL=postgres://postgres:password000@localhost:5432/newsletter
cargo test

The integration tests create isolated test databases and run migrations against them.

Database

Migrations live in migrations/ and are part of the application source.

Roadmap

Planned work:

• Deployment and production readiness
• Subscriber input validation
• Error handling
• Newsletter delivery
• API security
• Final polish

The deployment section will cover containerization, Docker image builds, SQLx offline mode, hierarchical configuration, database connectivity, image optimization and deployment to a managed platform.

License

This project is licensed under the MIT License. See LICENSE.