docs: add local developer setup (#12)

---------

Co-authored-by: Tom Winter <[email protected]>

docs/developer/README.md

@@ -0,0 +1,69 @@
+## Getting started
+
+### start local environment
+
+You can start all services needed for the local development with docker-compose:
+
+```shell
+docker compose -f docker-compose.yml -p aam-services up -d
+```
+
+#### Caddy (reverse-proxy)
+
+Part of the deployed services is a reverse-proxy. If you need to change the behavior, adapt the `./reverse-proxy/Caddyfile`
+and restart the reverse-proxy container.
+
+If you need local TLS support, you will need to import the Caddy Root CA.
+
+Install `caddy` on your local machine:
+
+MacOS:
+```shell
+brew install caddy
+```
+
+Trust the Caddy Root CA for local testing:
+```shell
+# make sure, that the docker container is running
+caddy trust
+```
+
+### useful tips and tricks
+
+#### Reset http/https redirect cache in chrome
+
+Sometimes, when you're playing around with `http(s)://` redirects in your browser,
+Chrome will cache the redirect for some time. When you explicit want to open
+the `http://` version of an url, but Chrome will not let you:
+
+- go to `chrome://net-internals/#hsts`
+- insert your domain in the `Delete domain security policies` section
+- press `delete`
+
+You can open the `http://` version directly again. 
+
+
+---
+# initial setup with related services
+1. start the docker-compose here
+2. if necessary, switch the image in docker-compose.yml from aam-sqs-mac to aam-sqs-linux
+
+Set up Keycloak
+3. create dummy-realm in the Keycloak Admin UI (http://localhost:8080), importing the current [ndb-setup realm_config.example.json](https://github.com/Aam-Digital/ndb-setup/blob/master/keycloak/realm_config.example.json)
+4. import client in [Keycloak Realm > Clients](http://localhost:8080/admin/master/console/#/dummy-realm/clients), using [ndb-setup client.json](https://github.com/Aam-Digital/ndb-setup/blob/master/keycloak/client_config.json)
+5. create a user in the new realm and assign it some relevant roles
+6. copy a Config:CONFIG_ENTITY doc into the couchdb: http://localhost:5984/_utils/#database/app/_all_docs (e.g. from https://dev.aam-digital.net/db/couchdb/_utils/#database/app/Config%3ACONFIG_ENTITY)
+
+Start backend:
+7. get the public_key for the realm from http://localhost:8080/realms/dummy-realm and add it to the replication-backend .env (JWT_PUBLIC_KEY)
+8. start the replication-backend (`npm start:dev`)
+
+Start frontend:
+9. switch config (environment.ts or assets/config.json) to `"session_type": "synced", "demo_mode": false`
+10. start the frontend (`npm start`)
+
+You now have a fully local environment with all relevant services:
+- App (frontend): http://localhost:4200
+- Replication backend: http://localhost:3000
+- Keycloak: http://localhost:8080
+- CouchDB: http://localhost:5984

docs/developer/docker-compose.yml

@@ -0,0 +1,85 @@
+# ***************************************************************
+# start local development environment (without application)
+# ***************************************************************
+
+version: '3'
+name: aam-services
+services:
+  reverse-proxy:
+    image: caddy:alpine
+    volumes:
+      - ./reverse-proxy/Caddyfile:/etc/caddy/Caddyfile
+    ports:
+      - "80:80"
+      - "443:443"
+      - "2019:2019"
+
+  maildev:
+    image: maildev/maildev
+    ports:
+      - "1025:1025"
+      - "1080:1080"
+
+  db-couch:
+    image: couchdb:3.3
+    volumes:
+      - ~/docker-volumes/aam-digital/aam-services/db-couch/document-data:/opt/couchdb/data
+      - ~/docker-volumes/aam-digital/aam-services/db-couch/document-etc-locald:/opt/couchdb/etc/local.d
+      - ~/docker-volumes/aam-digital/aam-services/db-couch/document-log:/opt/couchdb/log
+    environment:
+      COUCHDB_USER: admin
+      COUCHDB_PASSWORD: docker
+      COUCHDB_SECRET: docker
+    ports:
+      - "5984:5984"
+
+  db-keycloak:
+    image: postgres:16
+    volumes:
+      - ~/docker-volumes/aam-digital/aam-services/db-keycloak/postgresql-data:/var/lib/postgresql/data
+    environment:
+      POSTGRES_DB: postgres
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: keycloak
+    ports:
+      - "5432:5432"
+
+  rabbitmq:
+    image: rabbitmq:3-management-alpine
+    volumes:
+      - ~/docker-volumes/aam-digital/aam-services/rabbitmq/data:/var/lib/rabbitmq/
+      - ~/docker-volumes/aam-digital/aam-services/rabbitmq/log:/var/log/rabbitmq
+    ports:
+      - "5672:5672"
+      - "15672:15672"
+
+  sqs:
+    image: ghcr.io/aam-digital/aam-sqs-mac:latest
+    platform: linux/amd64
+    depends_on:
+      - db-couch
+    ports:
+      - "4984:4984"
+    volumes:
+      - ~/docker-volumes/aam-digital/aam-services/sqs/data:/data
+    environment:
+      SQS_COUCHDB_URL: http://db-couch:5984
+
+  keycloak:
+    image: quay.io/keycloak/keycloak:23.0
+    volumes:
+      - ~/docker-volumes/aam-digital/aam-services/keycloak/data:/opt/keycloak/data
+    ports:
+      - "8080:8080"
+    environment:
+      KC_DB: postgres
+      KC_DB_URL: jdbc:postgresql://db-keycloak:5432/postgres
+      KC_DB_SCHEMA: public
+      KC_DB_USERNAME: postgres
+      KC_DB_PASSWORD: keycloak
+      KEYCLOAK_ADMIN: admin
+      KEYCLOAK_ADMIN_PASSWORD: docker
+    depends_on:
+      - db-keycloak
+    command:
+      - start-dev

docs/developer/reverse-proxy/Caddyfile

@@ -0,0 +1,28 @@
+{
+	auto_https disable_redirects
+	admin 0.0.0.0:2019
+}
+
+auth.localhost:80, auth.localhost:443 {
+	handle /* {
+		reverse_proxy keycloak:8080
+	}
+}
+
+couchdb.localhost:80, couchdb.localhost:443 {
+	handle /* {
+		reverse_proxy db-couch:5984
+	}
+}
+
+sqs.localhost:80, sqs.localhost:443 {
+	handle /* {
+		reverse_proxy sqs:4984
+	}
+}
+
+localhost:80, localhost:443 {
+	handle /api/v1/reporting/* {
+		reverse_proxy host.docker.internal:3000
+	}
+}