From 9a8262b44a00a180136789c549d32cafe28e97fe Mon Sep 17 00:00:00 2001
From: Tom Wiesing <tkw01536@gmail.com>
Date: Mon, 1 Apr 2024 17:16:29 +0200
Subject: [PATCH] Add more documentation to each instance

This commit adds a new "README.md" file to each instance, adding more
documentation.
---
 internal/dis/component/stack.go               | 44 +++++++++++++++++--
 .../wisski/ingredient/barrel/barrel/README.md | 26 +++++++++++
 .../barrel/barrel/docker-compose.yml          |  1 -
 pkg/compose/env.go                            |  2 +-
 4 files changed, 67 insertions(+), 6 deletions(-)
 create mode 100644 internal/wisski/ingredient/barrel/barrel/README.md

diff --git a/internal/dis/component/stack.go b/internal/dis/component/stack.go
index e112c18..55a1b1d 100644
--- a/internal/dis/component/stack.go
+++ b/internal/dis/component/stack.go
@@ -220,16 +220,21 @@ func (is StackWithResources) Install(ctx context.Context, progress io.Writer, co
 		}
 	}
 
+	dockerComposeYML := filepath.Join(is.Dir, "docker-compose.yml")
+
 	// update the docker compose file
 	if is.ComposerYML != nil {
-		dst := filepath.Join(is.Dir, "docker-compose.yml")
-		fmt.Fprintf(progress, "[install] %s\n", dst)
-
-		if err := doComposeFile(dst, is.ComposerYML); err != nil {
+		fmt.Fprintf(progress, "[install] %s\n", dockerComposeYML)
+		if err := doComposeFile(dockerComposeYML, is.ComposerYML); err != nil {
 			return err
 		}
 	}
 
+	if err := addComposeFileHeader(dockerComposeYML); err != nil {
+		fmt.Fprintf(progress, "[update] %s\n", dockerComposeYML)
+		return err
+	}
+
 	// configure .env
 	envDest := filepath.Join(is.Dir, ".env")
 	if is.EnvContext != nil {
@@ -315,6 +320,37 @@ func (is StackWithResources) Install(ctx context.Context, progress io.Writer, co
 	return nil
 }
 
+const composeFileHeader = "# This file was automatically created and is updated by the distillery; DO NOT EDIT.\n\n"
+
+// addComposeFileHeader adds a header to the 'docker-compose.yml' file
+// indicating it is automatically created
+func addComposeFileHeader(path string) error {
+	// read existing bytes
+	bytes, err := os.ReadFile(path)
+	if err != nil {
+		return err
+	}
+
+	// overwrite the file
+	f, err := os.OpenFile(path, os.O_WRONLY|os.O_TRUNC, umaskfree.DefaultFilePerm)
+	if err != nil {
+		return err
+	}
+	defer f.Close()
+
+	// write the header
+	if _, err := f.WriteString(composeFileHeader); err != nil {
+		return nil
+	}
+
+	// write the original content
+	if _, err := f.Write(bytes); err != nil {
+		return err
+	}
+
+	return nil
+}
+
 // doComposeFile updates the compose file using the update function.
 //
 // If the file at path already exists, calls update with the existing data.
diff --git a/internal/wisski/ingredient/barrel/barrel/README.md b/internal/wisski/ingredient/barrel/barrel/README.md
new file mode 100644
index 0000000..c99daab
--- /dev/null
+++ b/internal/wisski/ingredient/barrel/barrel/README.md
@@ -0,0 +1,26 @@
+This folder contains all files relevant to a specific WissKI Distillery instance.
+This documentation provides basic information about all files and may be updated in future changes.
+
+## Container Files
+
+These are required for the container to function properly.
+DO NOT EDIT THESE, changes will be overwritten during the next rebuild.
+
+- `docker-compose.yml`: Defines how the docker image is run
+- `Dockerfile`: Dockerfile used to run the actual image
+- `.env`: Parameters for `docker-compose.yml`
+- `apache.d`, `scripts`, `php.ini.d`: Resources used during the docker-compose build.
+
+To tweak parameters inside the `.env` file, rebuild the image via `wdcli rebuild`.
+
+## Data Files
+
+These contain user data and settings for the instance.
+You can edit these (changes will __not__ be overwritten).
+Editing these may still risk breaking your instance; do so at your own risk.
+
+- `data`: Drupal Installation and user home directory
+- `ssh`: SSH Host keys; modify at your own risk
+- `settings.local.php`: settings.php added to this distillery instance
+- `prefixes.skip`: If this file exists, prefixes from this wisski instance will not be added to the global resolver.
+
diff --git a/internal/wisski/ingredient/barrel/barrel/docker-compose.yml b/internal/wisski/ingredient/barrel/barrel/docker-compose.yml
index cacecdb..8fde326 100644
--- a/internal/wisski/ingredient/barrel/barrel/docker-compose.yml
+++ b/internal/wisski/ingredient/barrel/barrel/docker-compose.yml
@@ -1,4 +1,3 @@
-# THIS FILE IS GENERATED AUTOMATICALLY. DO NOT EDIT.
 version: "3.7"
 
 services:
diff --git a/pkg/compose/env.go b/pkg/compose/env.go
index 2b8eea2..715eb53 100644
--- a/pkg/compose/env.go
+++ b/pkg/compose/env.go
@@ -9,7 +9,7 @@ import (
 )
 
 const (
-	EnvFileHeader = "# THIS FILE IS AUTOMATICALLY GENERATED. DO NOT EDIT. \n\n"
+	EnvFileHeader = "# This file is automatically created and updated by the distillery; DO NOT EDIT.\n\n"
 
 	EnvEqualChar   = '='  // assignment
 	EnvReplaceChar = '#'  // replacement for invalid characters