diff --git a/docs/developer/README.md b/docs/developer/README.md new file mode 100644 index 0000000..2e3cdec --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/developer/docker-compose.yml b/docs/developer/docker-compose.yml new file mode 100644 index 0000000..307207b --- /dev/null +++ b/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 diff --git a/docs/developer/reverse-proxy/Caddyfile b/docs/developer/reverse-proxy/Caddyfile new file mode 100644 index 0000000..670b9ca --- /dev/null +++ b/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 + } +}