doc: add docker development environment notes #118

Author: hernanvicente

README.md

@@ -21,7 +21,7 @@ Clone the codebase
 git clone [email protected]:rubyforgood/skillrx.git
 ``` 
 
-Run the setup script to prepare DB and assets
+Run the setup script to prepare the DB and assets
 ```sh
 bin/setup
 ```
@@ -73,3 +73,88 @@ This project uses:
 * `factory_bot` for making records
 
 To run tests simply use `bin/rspec`. You can also you `bin/quality` to check for code style issues.
+
+# Docker Development Environment
+
+This project is containerized using Docker to ensure consistent development environments across the team.
+
+## Prerequisites
+
+- Docker Engine installed on your system
+- Docker Compose V2 or later
+
+## Initial Setup
+
+1. Copy the environment configuration file:
+   ```bash
+   cp .env.example .env
+   ```
+2. Configure the environment variables in .env according to your needs. These variables control the behavior of the containerized services.
+
+3. Build and start the containers:
+    ```bash
+    docker compose up
+    ```
+
+This will build the images and initialise the containers. You can exit and stop the containers using CTRL+C.
+
+## Container Architecture
+The development environment consists of three containerized services:
+
+* app : Rails application service
+    * Handles the main application logic
+    * Runs on Ruby on Rails
+* db : PostgreSQL database service
+    * Persists application data 
+    * Runs independently from the application
+* localstack : AWS S3 emulator
+     * Provides local S3-compatible storage
+     * Enables development without actual AWS setup
+
+## Development Workflow
+
+We provide a Makefile to simplify common development tasks. Here are the most frequently used commands:
+```
+  make build             # Build image containers
+  make start [service]   # Start all containers or a specific service
+  make stop [service]    # Stop all containers or a specific service
+  make shell             # Open a bash shell in the app container
+  make console           # Start Rails console
+  make test              # Run all tests
+```
+
+For a complete list of available commands:
+```bash
+make help
+```
+
+## Common Tasks
+### Rebuilding the Environment
+To completely rebuild your development environment:
+
+```bash
+make rebuild
+```
+This command will clean existing containers, rebuild images, and prepare the database.
+
+### Viewing Logs
+To monitor service logs:
+```
+make logs         # View all container logs
+make logs app     # View only Rails application logs
+```
+
+### Container Management
+Individual services can be managed using:
+```
+make start db     # Start only the database container
+make stop app     # Stop only the application container
+make restart db   # Restart only the database container
+```
+
+### Troubleshooting
+If you encounter issues:
+- Ensure all required ports are available on your system
+- Verify that your .env file contains all necessary variables
+- Try rebuilding the environment with make rebuild
+- Check container logs for specific error messages