From 53a90e28b493d1b4056f1403d245eb071809af12 Mon Sep 17 00:00:00 2001
From: Timm Fitschen <t.fitschen@indiscale.com>
Date: Fri, 21 Mar 2025 10:09:34 +0100
Subject: [PATCH] WIP: document env.defaults, make overrides in env.local

---
 .env                               | 20 --------
 .gitignore                         |  2 +
 Makefile                           | 11 ++++-
 README.md                          | 68 ++++++++++++++++++---------
 docker-compose.yml                 |  2 +-
 env.defaults                       | 75 ++++++++++++++++++++++++++++++
 handle_server/run_handle_server.sh |  1 -
 7 files changed, 135 insertions(+), 44 deletions(-)
 delete mode 100644 .env
 create mode 100644 env.defaults

diff --git a/.env b/.env
deleted file mode 100644
index a3d372c..0000000
--- a/.env
+++ /dev/null
@@ -1,20 +0,0 @@
-COMPOSE_PROJECT_NAME=${COMPOSE_PROJECT_NAME:-test-handle-system}
-DOCKER_SUBNET_PREFIX=${DOCKER_SUBNET_PREFIX:-172.27}
-DOCKER_SUBNET=${DOCKER_SUBNET_PREFIX}.0.0/16
-DOCKER_SUBNET_GATEWAY=${DOCKER_SUBNET_PREFIX}.0.1
-HANDLE_SERVER_IPV4_ADDRESS=${DOCKER_SUBNET_PREFIX}.0.2
-HANDLE_SERVER_BIND_ADDRESS=${HANDLE_SERVER_IPV4_ADDRESS}
-
-HANDLE_SERVER_TCP_PORT=2641
-HANDLE_SERVER_UDP_PORT=2641
-HANDLE_SERVER_HTTP_PORT=8000
-HANDLE_SERVER_ORG_NAME="Test Inc."
-HANDLE_SERVER_CONTACT_NAME="Ms Test"
-HANDLE_SERVER_CONTACT_EMAIL="test@example.com"
-HANDLE_SERVER_LOG_SAVE_INTERVAL="Monthly"
-
-
-# HANDLE_SERVER_HOME_PREFIX without "0.NA/" prefix.
-HANDLE_SERVER_HOME_PREFIX="TEST"
-# USE_PUBLIC_HANDLE_SYSTEM="TRUE"
-USE_PUBLIC_HANDLE_SYSTEM="FALSE"
diff --git a/.gitignore b/.gitignore
index 079be0c..0bdbfc7 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1 +1,3 @@
 .handle/
+env.local
+.env
diff --git a/Makefile b/Makefile
index 9ae9fc0..fb814c0 100644
--- a/Makefile
+++ b/Makefile
@@ -1,14 +1,22 @@
-start: .handle
+start: .env .handle
 	@echo "Start Handle System"
 	docker compose up --build --detach
 	. ./.env && docker exec $${COMPOSE_PROJECT_NAME}-hs-server /hs/templates/wait-for-it.sh $${HANDLE_SERVER_IPV4_ADDRESS}:$${HANDLE_SERVER_HTTP_PORT} -t 500 -- echo "HANDLE SERVICE ONLINE"
 	. ./.env ; [ "$${USE_PUBLIC_HANDLE_SYSTEM}" = "TRUE" ] || docker exec $${COMPOSE_PROJECT_NAME}-hs-server bin/hdl-genericbatch /hs/setup.batch.hdl
 
+.env: env.defaults env.local
+	cat env.defaults > .env
+	cat env.local >> .env
+
+env.local:
+	touch $@
+
 .handle:
 	mkdir $@
 
 stop:
 	@echo "Stop Handle System"
+	[ -e .env ] || $(MAKE) .env
 	. ./.env && docker compose down
 
 clean: stop
@@ -16,3 +24,4 @@ clean: stop
 	rm -rf .handle
 	. ./.env && docker compose down -v --rmi all
 	. ./.env && docker compose rm -vsf
+	rm .env
diff --git a/README.md b/README.md
index 14178cb..afa4655 100644
--- a/README.md
+++ b/README.md
@@ -2,9 +2,9 @@
 
 This repository builds a HANDLE.NET server inside a docker container. The
 server is configured to create a private handle network using a single Prefix,
-"0.TEST".
+"TEST".
 
-This repository also contains a private keys for the 0.TEST/ADMIN handle and
+This repository also contains a private keys for the TEST/ADMIN handle and
 more data which should never be public under normal circumstances. However,
 this setup is intended for **testing purposes only**. In other words:
 
@@ -21,7 +21,6 @@ make start
 Open `https://172.27.0.2:8000` in your browser. You should see the HANDLE.NET
 landing page where you can resolve a handle.
 
-
 ## Test Web-based Admin Tool
 
 Open "https://172.27.0.2:8000/admin to see the admin tool.
@@ -70,7 +69,29 @@ Copy the whole `.handle` directory to `$HOME/.handle`. Warning: This will
 configure ALL handle clients running under your user account to use the private
 handle network.
 
-## Change IP Address of the Server
+## Wipe Database
+
+The database is preserved when your stop the server with
+
+```
+make stop
+```
+
+You can remove all persistent data by removing the container and the volume:
+
+```
+make clean
+```
+
+## Configuration
+
+When you run `make start`, the `.env` file is being created by concatenating
+`env.defaults` and `env.local`. Please make local adjustments to `env.local`
+but have a look at `env.defaults` for inspiration and documentation.
+
+## Troubleshooting
+
+### Failed to Create Network Due to IP Range Conflicts
 
 By default, the IP address of the server is configured to be `172.27.0.2`. The
 server is only available in from your host machine because docker is creating
@@ -81,30 +102,35 @@ the network for you that way.
 > one on this address space
 
 Should there be a problem, e.g. the address range is also used by your LAN or
-by other docker networks, you can change the `.env` file. E.g. try `172.26`
-instead of `172.26` as the `DOCKER_SUBNET_PREFIX` or run
-
-```
-DOCKER_SUBNET_PREFIX=172.26 make start
+by other docker networks, you can make adjustments in the `env.local` file.
+You need to override the following variables:
+* `DOCKER_SUBNET_PREFIX`
+* `DOCKER_SUBNET`
+* `DOCKER_SUBNET_GATEWAY`
+* `HANDLE_SERVER_IPV4_ADDRESS`
+* `HANDLE_SERVER_BIND_ADDRESS`
 
-Note: If you have started the server in the past you might need to remove the
-docker network by hand before you can start the server with the new
-IP address configuration: `docker network rm test-handle-system-hs-network`
+It is recommended to copy-paste the content of `env.default` and adjust it.
+E.g. try `172.26` instead of `172.26` as the `DOCKER_SUBNET_PREFIX`.
 
-## Wipe Database
+#### Quick-end-dirty Alternative
 
-The database is preserved when your stop the server with
+As non-persistent way to change the IP configuration just run:
 
 ```
-make stop
+DOCKER_SUBNET_PREFIX=172.26 make start
 ```
 
-You can remove all persistent data by removing the container and the volume:
-
-```
-make clean
-```
+> Note: If you have started the server in the past you might need to remove the
+> docker network by hand before you can start the server with the new
+> IP address configuration: `docker network rm test-handle-system-hs-network`
 
 ## Licence
 
-(C) 2024 by Timm C. Fitschen (t.fitschen@indiscale.com) is licensed under CC BY 4.0
+[AGPL-v3-or-later](./LICENSE)
+
+## Copyright
+
+* Copyright (C) 2024-2025 Timm Fitschen <t.fitschen@indiscale.com>
+* Copyright (C) 2024-2025 IndiScale GmbH <info@indiscale.com>
+
diff --git a/docker-compose.yml b/docker-compose.yml
index fce44c8..89343dc 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -6,7 +6,7 @@ services:
     env_file: .env
     networks:
       hs-network:
-        ipv4_address: ${HANDLE_SERVER_IPV4_ADDRESS}
+        ipv4_address: ${DOCKER_CONTAINER_IPV4_ADDRESS}
     volumes:
       ## make handle server persistent
       #- type: bind
diff --git a/env.defaults b/env.defaults
new file mode 100644
index 0000000..6a813a6
--- /dev/null
+++ b/env.defaults
@@ -0,0 +1,75 @@
+################################################
+# !!! DO NOT EDIT. EDIT env.local instead. !!! #
+################################################
+
+# COMPOSE_PROJECT_NAME - The prefix of the docker container, volume and network created by docker compose.
+# This is just a convenient way to make this env file respect the pre-defined `COMPOSE_PROJECT_NAME` to
+# override this, ...
+_COMPOSE_PROJECT_NAME=${COMPOSE_PROJECT_NAME:-}
+# ... just copy this line to your `env.local` and change "test-handle-system" to your desired value.
+COMPOSE_PROJECT_NAME=${_COMPOSE_PROJECT_NAME:-test-handle-system}
+
+
+# DOCKER_SUBNET_PREFIX - The class B private network used by docker - but only the first two bytes.
+# This is a convenient way to set all the network related variables reliably at once.
+DOCKER_SUBNET_PREFIX=${DOCKER_SUBNET_PREFIX:-172.27}
+
+# DOCKER_SUBNET - The class B private network used by docker - full definition.
+# Actually, it is possible to use class A or C networks as well, but this is a sensible default.
+DOCKER_SUBNET=${DOCKER_SUBNET_PREFIX}.0.0/16
+
+# DOCKER_SUBNET_GATEWAY - The gateway to be used by the docker network.
+# Don't touch this, only keep it consistent with the DOCKER_SUBNET.
+# `0.1` is the docker hosts IP address, so this is a sensible default.
+DOCKER_SUBNET_GATEWAY=${DOCKER_SUBNET_PREFIX}.0.1
+
+# DOCKER_CONTAINER_IPV4_ADDRESS - the ip address of the docker container running
+# the Handle server.
+DOCKER_CONTAINER_IPV4_ADDRESS=${DOCKER_SUBNET_PREFIX}.0.2
+
+# COMPOSE_BAKE - Use Bake to build the images.
+# Set to false if you don't have bake.
+# Bake is supposed to be faster than docker's default but Bake is not necessary.
+COMPOSE_BAKE=true
+
+# HANDLE_SERVER_IPV4_ADDRESS - The address of the Handle server (from outside).
+# If you make the Handle server available in your LAN you need your hosts IP
+# address here.
+HANDLE_SERVER_IPV4_ADDRESS=${DOCKER_CONTAINER_IPV4_ADDRESS}
+
+# HANDLE_SERVER_BIND_ADDRESS - The bind address of the Handle server.
+# This is the address the handle server is listening on. This should always be the
+# DOCKER_CONTAINER_IPV4_ADDRESS.
+HANDLE_SERVER_BIND_ADDRESS=${DOCKER_CONTAINER_IPV4_ADDRESS}
+
+# HANDLE_SERVER_TCP_PORT - The port of the DO-IRP over TCP interface.
+HANDLE_SERVER_TCP_PORT=2641
+# HANDLE_SERVER_TCP_PORT - The port of the DO-IRP over UDP interface.
+HANDLE_SERVER_UDP_PORT=2641
+# HANDLE_SERVER_TCP_PORT - The port of the HTTP(S) interface.
+HANDLE_SERVER_HTTP_PORT=8000
+# HANDLE_SERVER_ORG_NAME - Information on the handle server's provider
+HANDLE_SERVER_ORG_NAME="Test Inc."
+# HANDLE_SERVER_CONTACT_NAME - Information on the handle server's provider
+HANDLE_SERVER_CONTACT_NAME="Ms Test"
+# HANDLE_SERVER_CONTACT_EMAIL - Information on the handle server's provider
+HANDLE_SERVER_CONTACT_EMAIL="test@example.com"
+
+# HANDLE_SERVER_LOG_SAVE_INTERVAL - Interval of the log rotation.
+# Log files are being written to `/hs/srv_1/logs/`.
+# You can bind mount that directory or docker-copy it you you want to access that
+# information.
+HANDLE_SERVER_LOG_SAVE_INTERVAL="Monthly"
+
+
+# HANDLE_SERVER_HOME_PREFIX - The handle prefix managed by this Handle server 
+# (without leading "0.NA/")
+HANDLE_SERVER_HOME_PREFIX="TEST"
+# USE_PUBLIC_HANDLE_SYSTEM - Experimental flag to run the server as part of the public Handle system.
+# Switch to USE_PUBLIC_HANDLE_SYSTEM="TRUE" if desired.
+USE_PUBLIC_HANDLE_SYSTEM="FALSE"
+
+
+#####################################################
+# Begin of overrides and locally defined variables. #
+#####################################################
diff --git a/handle_server/run_handle_server.sh b/handle_server/run_handle_server.sh
index 53f41ce..be40419 100755
--- a/handle_server/run_handle_server.sh
+++ b/handle_server/run_handle_server.sh
@@ -25,7 +25,6 @@ fi
 
 # ### Update configuration ###
 # update config.dct
-echo "HERE ##################"
 if [ "$USE_PUBLIC_HANDLE_SYSTEM" = "TRUE" ] ; then
     . public.defaults.sh
 else
-- 
GitLab