Hexlet SICP

Read this in another language: Русский

Hexlet SICP is a service for those studying the book Structure and Interpretation of Computer Programs. Track your progress and match yourself against others on the global leaderboard.

How to study Structure and Interpretation of Computer Programs (SICP)

For contributors

• Discuss the project on Telegram: https://t.me/hexletcommunity/12

Recorded meetings

• Recorded meetings playlist

FAQ

Q: I get this error Illuminate\Session\TokenMismatchException: CSRF token mismatch. A: Reset your config cache php artisan config:clear

Requirements

Run composer check-platform-reqs to check PHP deps:

• PHP ^8.5
• Composer
• Node.js 24+ & pnpm (corepack enable pnpm — version is pinned in package.json)
• PostgreSQL 18 (locally you can run it from docker compose, see below)
• heroku cli; How to deploy Laravel on Heroku (in Russian)

What is a Version Manager?

Setup

Local setup

The app runs on PostgreSQL everywhere: locally, in tests, on stage and in production. The simplest way to get a database is the container from docker compose — it listens on 127.0.0.1:54320 and creates both databases, the application one and the test one.

make compose-start-database # start PostgreSQL in a container
make setup                  # set up the project
make start                  # start server at http://127.0.0.1:8000/
make test                   # run tests

Connection settings are taken from .env, which make setup copies from .env.example. Their defaults match the container above, so nothing has to be edited.

To use your own PostgreSQL instead of the container, change DB_* and TEST_DB_* in .env (the default port is 5432) and create both databases by hand:

createdb hexlet_sicp
createdb hexlet_sicp_test

Tests recreate the schema on every run, so they use a separate database — never point TEST_DB_DATABASE at the one you develop against.

Setup in Docker

make compose-setup # build project
make compose-start # start server at http://127.0.0.1:8000/
make compose-bash  # start bash session inside docker container
make test          # run tests inside docker container

Inside the containers the database host is set by docker-compose.yml, so the DB_HOST and DB_PORT values from .env are not used there.

Stage deployment

Stage environment uses Docker Compose to deploy a production-like setup on a single server.

Architecture:

• app - Laravel application container (serves HTTP on port 80)
• queue - background queue worker
• db - PostgreSQL database

Initial setup (first time only):

1. Prepare the .env file on the server

   cp .env.example .env
   nano .env
   

2. Configure environment variables (see docker-compose.stage.yml)

   APP_ENV=production
   APP_DEBUG=false
   APP_URL=https://your-domain.com
   PRODUCTION_URL=https://your-domain.com
   
   DB_CONNECTION=pgsql
   DB_HOST=db
   DB_PORT=5432
   DB_DATABASE=hexlet_sicp
   DB_USERNAME=sicp_user
   DB_PASSWORD=your_secure_password
   
   QUEUE_CONNECTION=database
   SESSION_DRIVER=cookie
   

3. Run initial setup

   make stage-setup
   

   This will:

   • Start all containers
   • Generate application key
   • Run migrations with seeders
   • Create storage symlink
   • Build config/route/view caches

Deploying updates:

make stage-deploy

This will:

• Pull latest code from git (main branch)
• Rebuild containers
• Run new migrations
• Clear and rebuild caches

Deploying a specific branch:

make stage-deploy-branch BRANCH=feature/my-feature

This will:

• Fetch and checkout the specified branch
• Pull latest code from that branch
• Rebuild containers
• Run new migrations
• Clear and rebuild caches

Other commands:

make stage-start    # Start containers
make stage-stop     # Stop containers
make stage-restart  # Restart containers
make stage-logs     # View logs
make stage-bash     # Open bash in app container
make stage-down     # Stop and remove containers
make stage-reset    # Complete rebuild: stop, remove volumes, rebuild, and reinitialize

HTTPS setup:

The stage app listens on HTTP (port 80) only. For HTTPS, use an external reverse proxy (Caddy, Traefik, or host-level nginx) for TLS termination.

This is the beginning of the README. Read the rest at the original. Read the full README ↗