Setup Localstack AWS S3 for local development

.env.example

@@ -1,3 +1,19 @@
+RAILS_ENV=development
+DATABASE_USER=postgres
+DATABASE_PASSWORD=postgres
+DATABASE_NAME=skillrx_development
+DATABASE_PORT=5432
+DATABASE_HOST=db
+
+LOCALSTACK_DEBUG=1
+S3_SKIP_SIGNATURE_VALIDATION=0
+
+AWS_ACCESS_KEY_ID=test
+AWS_SECRET_ACCESS_KEY=test
+AWS_BUCKET_NAME=skillrx-development
+AWS_DEFAULT_REGION=us-east-1
+AWS_ENDPOINT_URL=http://localstack:4566
+
 AZURE_STORAGE_ACCOUNT_NAME=skillrx
 AZURE_STORAGE_ACCOUNT_KEY=skillrx
 AZURE_STORAGE_SHARE_NAME=skillrx

.localstack/config.json

@@ -0,0 +1,11 @@
+{
+  "services": {
+    "s3": {
+      "buckets": [
+        {
+          "name": "dev-bucket"
+        }
+      ]
+    }
+  }
+}

.tool-versions

@@ -0,0 +1 @@
+ruby 3.4.1

Dockerfile.dev

@@ -0,0 +1,48 @@
+# Use Ruby 3.x with Alpine as base image for smaller size
+FROM ruby:3.4.1-alpine
+
+# Set environment variables for Rails
+ENV RAILS_ENV=development \
+    RACK_ENV=development \
+    BUNDLE_PATH=/usr/local/bundle \
+    BUNDLE_JOBS=4 \
+    BUNDLE_RETRY=3
+
+# Install system dependencies and development tools
+RUN apk add --no-cache \
+    build-base \
+    postgresql-dev \
+    git \
+    tzdata \
+    bash \
+    nss \
+    freetype \
+    freetype-dev \
+    harfbuzz \
+    ca-certificates \
+    ttf-freefont \
+    chromium \
+    chromium-chromedriver
+
+# Set Chrome environment variables
+ENV CHROME_BIN=/usr/bin/chromium-browser \
+    CHROME_PATH=/usr/lib/chromium/
+
+# Create and set working directory
+WORKDIR /app
+
+# Install Ruby dependencies
+COPY Gemfile Gemfile.lock ./
+RUN bundle install
+
+# Add bind mount point for code
+VOLUME /app
+
+# Port used by Rails server
+EXPOSE 3000
+
+# Configure entrypoint to run Rails
+ENTRYPOINT ["./bin/docker-entrypoint.dev"]
+
+# Start Rails server by default
+CMD ["bundle", "exec", "rails", "server", "-b", "0.0.0.0"]

Gemfile

@@ -49,9 +49,8 @@ gem "thruster", require: false
 # Use Active Storage variants [https://guides.rubyonrails.org/active_storage_overview.html#transforming-images]
 gem "image_processing", "~> 1.14"
 
-# Add tagging functionality
 gem "acts-as-taggable-on"
-
+gem "aws-sdk-s3", require: false
 gem "requestjs-rails"
 
 group :development, :test do

Gemfile.lock

@@ -95,6 +95,24 @@ GEM
       public_suffix (>= 2.0.2, < 7.0)
     annotaterb (4.14.0)
     ast (2.4.3)
+    aws-eventstream (1.4.0)
+    aws-partitions (1.1110.0)
+    aws-sdk-core (3.225.0)
+      aws-eventstream (~> 1, >= 1.3.0)
+      aws-partitions (~> 1, >= 1.992.0)
+      aws-sigv4 (~> 1.9)
+      base64
+      jmespath (~> 1, >= 1.6.1)
+      logger
+    aws-sdk-kms (1.102.0)
+      aws-sdk-core (~> 3, >= 3.225.0)
+      aws-sigv4 (~> 1.5)
+    aws-sdk-s3 (1.189.0)
+      aws-sdk-core (~> 3, >= 3.225.0)
+      aws-sdk-kms (~> 1)
+      aws-sigv4 (~> 1.5)
+    aws-sigv4 (1.12.0)
+      aws-eventstream (~> 1, >= 1.0.2)
     base64 (0.3.0)
     bcrypt (3.1.20)
     bcrypt_pbkdf (1.1.1)
@@ -188,6 +206,7 @@ GEM
     jbuilder (2.13.0)
       actionview (>= 5.0.0)
       activesupport (>= 5.0.0)
+    jmespath (1.6.2)
     json (2.10.2)
     jwt (2.10.1)
       base64
@@ -473,6 +492,7 @@ DEPENDENCIES
   active_storage_validations
   acts-as-taggable-on
   annotaterb
+  aws-sdk-s3
   azure_file_shares!
   bcrypt (~> 3.1.7)
   bootsnap

Makefile

@@ -0,0 +1,90 @@
+# Project configuration
+
+# Docker uses the directory environment variable to set a prefix for the service's container names.
+# Doc: https://docs.docker.com/compose/how-tos/environment-variables/envvars/#compose_project_name
+PROJECT_NAME := sk
+
+# Colors for terminal output (optional)
+BLUE := \033[34m
+RESET := \033[0m
+
+# Commands configuration
+COMPOSE_CMD = COMPOSE_PROJECT_NAME=$(PROJECT_NAME) docker compose -f docker-compose.dev.yml
+DOCKER_TEST_CMD = $(COMPOSE_CMD) exec app bundle exec rspec --format documentation
+EXEC_CMD = $(COMPOSE_CMD) exec app
+
+.PHONY: help build rebuild stop start restart logs shell console format test test_fast db_reset migrate clean clean_volumes
+
+# Default target
+help:
+	@echo "$(BLUE)Available commands:$(RESET)"
+	@echo "  make build             - Build image containers"
+	@echo "  make rebuild           - Clean, build, start containers and prepare database"
+	@echo "  make stop [service]    - Stop all containers or a specific service"
+	@echo "  make start [service]   - Start all containers or a specific service"
+	@echo "  make restart [service] - Restart all containers or a specific service"
+	@echo "  make logs [service]    - View logs of all containers or a specific service"
+	@echo "  make shell				- Open a bash shell in the app container"
+	@echo "  make console           - Start Rails console"
+	@echo "  make format            - Auto-format code with Rubocop"
+	@echo "  make test              - Run all tests"
+	@echo "  make test_fast         - Run all tests and stop on first failure"
+	@echo "  make migrate           - Run database migrations"
+	@echo "  make db_reset          - Reset and rebuild database"
+	@echo "  make clean             - Remove all containers and volumes"
+	@echo "  make clean_volumes     - Remove all volumes"
+
+build:
+	$(COMPOSE_CMD) build
+	@echo "✅ Build complete!"
+
+rebuild:
+	@echo "🚀 Setting up..."
+	make clean
+	make build
+	make start
+	sleep 2
+	$(EXEC_CMD) bundle exec rails db:reset
+	@echo "✅ Setup complete!"
+
+stop:
+	$(COMPOSE_CMD) stop $(filter-out $@,$(MAKECMDGOALS))
+
+start:
+	$(COMPOSE_CMD) up -d $(filter-out $@,$(MAKECMDGOALS))
+
+restart:
+	$(COMPOSE_CMD) restart $(filter-out $@,$(MAKECMDGOALS))
+
+logs:
+	$(COMPOSE_CMD) logs -f $(filter-out $@,$(MAKECMDGOALS))
+
+shell:
+	$(EXEC_CMD) bash
+
+console:
+	$(EXEC_CMD) bundle exec rails console
+
+format:
+	$(EXEC_CMD) bundle exec rubocop --autocorrect-all
+
+test:
+	export RAILS_ENV=test $(DOCKER_TEST_CMD)
+
+test_fast:
+	$(DOCKER_TEST_CMD) --fail-fast
+
+migrate:
+	$(EXEC_CMD) bundle exec rails db:migrate
+
+db_reset:
+	$(EXEC_CMD) bundle exec rails db:drop db:create db:prepare
+
+clean:
+	$(COMPOSE_CMD) down -v
+
+clean_volumes:
+	docker volume rm -f $(PROJECT_NAME)_localstack_data $(PROJECT_NAME)_db_data
+
+%:
+	@:

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
 ```
@@ -72,4 +72,95 @@ This project uses:
 * `shoulda-matchers` for expectations
 * `factory_bot` for making records
 
-To run tests simply use `bin/rspec`. You can also you `bin/quality` to check for code style issues.
+To run tests, simply use `bin/rspec`. You can also use `bin/quality` to check for code style issues.
+
+# Docker Development Environment
+
+This project is containerised 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:
+   ```
+   cp .env.example .env
+   ```
+
+2. Configure the environment variables in `.env` as needed. These variables set up the containerised services. Update the `.env.example` file with any new or changed variables.
+
+3. To view the uploaded files from http://localstack:4566 in your browser, add the following line to your `/etc/hosts` to resolve `localstack` to your host system:
+    ```
+    127.0.0.1 	localstack
+    ```
+
+4. Build and start the containers:
+    ```
+    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 containerised 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

bin/docker-entrypoint.dev

@@ -0,0 +1,13 @@
+#!/bin/bash -e
+
+# Remove any existing server.pid file
+rm -f /app/tmp/pids/server.pid
+
+# Install new gems if any
+bundle check || bundle install
+
+# If running the rails server then create or migrate existing database
+./bin/rails db:prepare
+
+# Execute the main command passed to docker run
+exec "$@"

config/database.yml

@@ -15,6 +15,10 @@
 default: &default
   adapter: postgresql
   encoding: unicode
+  host: <%= ENV.fetch('DATABASE_HOST') { 'localhost' } %>
+  user: <%= ENV.fetch('DATABASE_USERNAME') { 'postgres' } %>
+  password: <%= ENV.fetch('DATABASE_PASSWORD') { 'postgres' } %>
+  port: <%= ENV.fetch('DATABASE_PORT') { 5432 }  %>
   # For details on connection pooling, see Rails configuration guide
   # https://guides.rubyonrails.org/configuring.html#database-pooling
   pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>

config/environments/development.rb

@@ -45,7 +45,7 @@
   config.solid_queue.logger = ActiveSupport::Logger.new(STDOUT)
 
   # Store uploaded files on the local file system (see config/storage.yml for options).
-  config.active_storage.service = :local
+  config.active_storage.service = ENV["DOCKER_CONTAINER"] == "true" ? :amazon : :local
 
   config.action_mailer.delivery_method = :letter_opener
   config.action_mailer.perform_deliveries = true

config/storage.yml

@@ -7,12 +7,14 @@ local:
   root: <%= Rails.root.join("storage") %>
 
 # Use bin/rails credentials:edit to set the AWS secrets (as aws:access_key_id|secret_access_key)
-# amazon:
-#   service: S3
-#   access_key_id: <%= Rails.application.credentials.dig(:aws, :access_key_id) %>
-#   secret_access_key: <%= Rails.application.credentials.dig(:aws, :secret_access_key) %>
-#   region: us-east-1
-#   bucket: your_own_bucket-<%= Rails.env %>
+amazon:
+  service: S3
+  access_key_id: <%= ENV['AWS_ACCESS_KEY_ID'] %>
+  secret_access_key: <%= ENV['AWS_SECRET_ACCESS_KEY'] %>
+  region: <%= ENV['AWS_DEFAULT_REGION'] %>
+  bucket: <%= ENV['AWS_BUCKET_NAME'] %>
+  endpoint: <%= ENV['AWS_ENDPOINT_URL'] %>
+  force_path_style: true
 
 # Remember not to checkin your GCS keyfile to a repository
 # google: