Docker development environment¶
Running Easy8 from the project image. For day-to-day development outside Docker see Set up a development environment.
Prerequisites¶
- Docker 26+ with BuildKit and Docker Compose (checked by
docker/build.sh). - An initial database, for example demo data.
Build the image¶
Run the build script from the Rails root:
The script starts an isolated Docker-in-Docker builder with a temporary Percona 8.4 database, builds the image from Dockerfile (it runs migrations, easy:setup and asset precompilation in a throwaway stage) and loads it as easy:latest. Set BASE_IMAGE_TAG to change the tag.
The image contains the application in /opt/easy/current; docker/env.EXAMPLE runs it with RAILS_ENV="production". To change application code, rebuild the image.
Run the stack¶
docker-compose.yml in the Rails root starts these services: db (Percona 8.4), redis (Redis 8), app (Puma), sidekiq and pdf_chrome (headless Chrome for PDF rendering). Set APP_IMAGE and create .env from docker/env.EXAMPLE:
Container commands, mount points and all environment variables are described in the Docker guide. The entrypoint (docker-entrypoint.sh) accepts install, server, sidekiq, start (install and server), rails <subcommand> and bash.
Database pool and concurrency¶
RAILS_MAX_WORKERS sets the number of Puma processes, RAILS_MAX_THREADS the request threads per process and SIDEKIQ_WORKERS the default-capsule job threads (default 2).
The ActiveRecord pool per process is DB_POOL when set, otherwise max(10, RAILS_MAX_THREADS, SIDEKIQ_WORKERS + 1) (config/database.yml). Do not multiply the pool size by the worker count. Parallel test processes each own a separate pool. Concurrency specs hold eight worker connections next to the test thread, so use a pool of at least 9 when you set DB_POOL for them.
Printable PDF rendering¶
PDF rendering uses the pdf_chrome service. Rails reaches it through PDF_CHROME_URL and Chrome reaches Rails through PDF_RENDER_BASE_URL:
When you run Rails outside Docker, start Chrome manually and make Rails reachable from its container:
docker run --rm -p 9222:9222 --add-host=host.docker.internal:host-gateway chromedp/headless-shell:stable --disable-gpu --disable-dev-shm-usage
PDF_CHROME_URL=http://localhost:9222 PDF_RENDER_BASE_URL=http://host.docker.internal:3000 bin/rails s -b 0.0.0.0
If printable template content references Vite dev assets directly, keep Vite reachable from the Chrome container as well, for example with VITE_RUBY_HOST=0.0.0.0 bin/vite dev.