From 804446deba3f54d5ddb7d4bc2d7f8be699628dd6 Mon Sep 17 00:00:00 2001
From: Jens <kontakt@jensheise.com>
Date: Tue, 29 Oct 2024 09:39:50 +0100
Subject: [PATCH] add simple dev environment

(cherry picked from commit 24a969818780e50ff853c622f40fed7e58968769)
---
 README.md                     |  4 ++
 docker/dev/Dockerfile         | 10 +++++
 docker/dev/README.md          | 78 +++++++++++++++++++++++++++++++++++
 docker/dev/docker-compose.yml | 42 +++++++++++++++++++
 docker/dev/entrypoint.sh      | 17 ++++++++
 5 files changed, 151 insertions(+)
 create mode 100644 docker/dev/Dockerfile
 create mode 100644 docker/dev/README.md
 create mode 100644 docker/dev/docker-compose.yml
 create mode 100644 docker/dev/entrypoint.sh

diff --git a/README.md b/README.md
index 3195255..3674f7b 100644
--- a/README.md
+++ b/README.md
@@ -35,3 +35,7 @@ Join us on this journey, whether you are a contributor, user or just a spectator
 The project and all participants are looking forward to your feedback, as we are continuously working to improve
 HARMONY and EIFFEL. The project is in active development.
 
+---
+
+For a simple development environment, consult [docker/dev](docker/dev/README.md).
+
diff --git a/docker/dev/Dockerfile b/docker/dev/Dockerfile
new file mode 100644
index 0000000..7bd9a87
--- /dev/null
+++ b/docker/dev/Dockerfile
@@ -0,0 +1,10 @@
+FROM golang:latest
+
+RUN curl -sSfL https://raw.githubusercontent.com/air-verse/air/master/install.sh | sh -s -- -b $(go env GOPATH)/bin
+
+WORKDIR /app
+
+COPY ./entrypoint.sh /entrypoint.sh
+RUN chmod +x /entrypoint.sh
+
+ENTRYPOINT ["/entrypoint.sh"]
\ No newline at end of file
diff --git a/docker/dev/README.md b/docker/dev/README.md
new file mode 100644
index 0000000..60d666a
--- /dev/null
+++ b/docker/dev/README.md
@@ -0,0 +1,78 @@
+# HARMONY Development Environment Guide
+
+## Getting Started
+
+The development environment runs in Docker containers and features hot-reload capabilities for Go code, and the project's dependencies (e.g. templates, translations, ...) using Air.
+
+### Prerequisites
+
+- Docker and Docker Compose installed (should come with Docker Desktop for Windows pre-installed!)
+- Git (for cloning the repository)
+
+### Starting the Development Environment
+
+1. Navigate to the development docker directory:
+
+```bash
+cd docker/dev
+```
+
+2. Start the environment:
+
+```bash
+docker compose up --build
+```
+
+The application will be available at `http://localhost:8080`. However, you'll still need DB migrations.
+
+You'll also have to set up your authorization provider of choice, consult the `config/auth.toml` for this. Consider putting your overwrite in `config/local/auth.toml` so that it's not commited to the VCS by accident.
+
+### Database Migrations
+
+Migrations can be controlled via the `RUN_MIGRATIONS` environment variable in `docker-compose.yml`:
+
+```yaml
+environment:
+  RUN_MIGRATIONS: true  # or false
+```
+
+**Important Notes:**
+
+- This setting can only be changed in the `docker-compose.yml` file
+- Setting it to `true` will run migrations on container startup
+- While migrations are versioned, keeping this enabled could lead to unexpected database changes when pulling new
+  migrations from remote
+- For controlled database updates, it's recommended to keep this `false` and run migrations manually when needed
+
+### Useful Docker Compose Commands
+
+```bash
+# Start in detached mode (run in background)
+docker compose up -d
+
+# Force recreation of containers
+docker compose up --force-recreate
+
+# Rebuild containers and start
+docker compose up --build
+
+# Stop and remove containers
+docker compose down
+
+# View logs when running in detached mode
+docker compose logs -f
+
+# Common combinations
+docker compose up -d --build  # Rebuild and start in background
+docker compose up --force-recreate --build  # Full rebuild and restart
+```
+
+### Development Workflow
+
+1. The entire project directory is mounted into the container
+2. Changes to Go files trigger automatic rebuilds via Air
+3. Application logs are visible in the Docker Compose output
+4. Database data persists across container restarts via Docker volumes
+
+Remember to rebuild the containers (`--build`) when making changes to the Docker configuration files or when new
+dependencies are added to the project.
\ No newline at end of file
diff --git a/docker/dev/docker-compose.yml b/docker/dev/docker-compose.yml
new file mode 100644
index 0000000..01e088f
--- /dev/null
+++ b/docker/dev/docker-compose.yml
@@ -0,0 +1,42 @@
+services:
+  dev-pg:
+    image: postgres:latest
+    container_name: harmony-dev-pg
+    environment:
+      POSTGRES_USER: harmony
+      POSTGRES_PASSWORD: devpassword
+      POSTGRES_DB: harmony
+      PGDATA: /var/lib/postgresql/data/pgdata
+    volumes:
+      - harmony-dev-pg-data:/var/lib/postgresql/data
+    expose:
+      - "5432"
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U harmony"]
+      interval: 1s
+      timeout: 1s
+      retries: 15
+
+  dev-app:
+    build:
+      context: .
+    container_name: harmony-dev-app
+    volumes:
+      - ../..:/app
+    environment:
+      DB_HOST: dev-pg
+      DB_PORT: 5432
+      DB_USER: harmony
+      DB_PASS: devpassword
+      DB_NAME: harmony
+      PORT: 8080
+      RUN_MIGRATIONS: true
+    ports:
+      - "8080:8080"
+    depends_on:
+      dev-pg:
+        condition: service_healthy
+
+volumes:
+  harmony-dev-pg-data:
+    name: harmony-dev-pg-data
\ No newline at end of file
diff --git a/docker/dev/entrypoint.sh b/docker/dev/entrypoint.sh
new file mode 100644
index 0000000..6eb2eb4
--- /dev/null
+++ b/docker/dev/entrypoint.sh
@@ -0,0 +1,17 @@
+#!/bin/bash
+set -e
+
+if [ "$RUN_MIGRATIONS" = "true" ]; then
+    # TODO simplify, to speed up
+    echo "Building migration tool..."
+    go build -o migrate src/cmd/migrate/*.go
+
+    echo "Running migrations..."
+    ./migrate up
+
+    echo "Removing migration tool..."
+    rm ./migrate
+fi
+
+echo "Starting development server..."
+exec air
\ No newline at end of file
-- 
GitLab