From 40ff6408f3efc05a410d0c6a61ac1f171c99016f Mon Sep 17 00:00:00 2001
From: rmanach <romain.manach@intercloud.com>
Date: Fri, 4 Apr 2025 09:37:21 +0200
Subject: [PATCH] add README

---
 Makefile  |  11 ++++-
 README.md | 129 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 139 insertions(+), 1 deletion(-)
 create mode 100644 README.md

diff --git a/Makefile b/Makefile
index db49554..264c77f 100644
--- a/Makefile
+++ b/Makefile
@@ -1,9 +1,18 @@
+BIN_NAME = "hmdeploy"
+
 run: lint
 	@go run main.go
 
 build: lint
-	@go build -o hmdeploy main.go
+	@echo "building binary..."
+	@go build -o $(BIN_NAME) -race main.go && echo "$(BIN_NAME) built"
+
+install:
+	@$(shell whereis $(BIN_NAME) | cut -d ' ' -f2 | xargs rm -f)
+	@go install
+	@echo "program installed: $(GOPATH)/bin/hmdeploy"
 
 lint:
+	@echo "format and lint..."
 	@golangci-lint fmt ./...
 	@golangci-lint run ./...
\ No newline at end of file
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..a9e27ef
--- /dev/null
+++ b/README.md
@@ -0,0 +1,129 @@
+# hmdeploy
+
+A program tool to deploy a dockerized application with Nginx as reverse proxy on **Proxmox**.
+This tool has been developed for **home server** deployment.
+For production environment, use it **with caution**.
+
+> **NOTE**: You must have **Docker** installed on your machine or the machine lauching the binary.
+
+## Why ?
+
+You have an Nginx instance in front of a Docker Swarm instance (ip are here for demonstration):
+```ascii
++-------------------------+          +-------------------------+            
+|docker swarm             |          |nginx                    |            
+|                         |          |                         |            
+|ip: 10.0.0.2             |          |ip: 10.0.0.1             |            
+|                         |          |                         | HTTP Request           
+|                         +----------+                         |<-----------
+|                         |          |                         |            
+|                         |          |                         |            
+|                         |          |                         |            
+|                         |          |                         |            
+|                         |          |                         |            
+|                         |          |                         |            
++-------------------------+          +-------------------------+
+```
+
+You want to deploy a service and its Nginx conf easyly with a simple CLI ? This tool is for you.
+No Terraform, no ansible or no extra tools, just one binary for all your projects.
+
+Yep, perhaps bash scripts was ok but this, enable to design deployment dependencies graph and launch it in workers.
+It has a nice logging and clean all the ressources (succeed or failed).
+
+## How ?
+
+* Create a folder in your `home` dir: `.homeserver`
+* Create a file inside named: `map.json`. This file will contain all network informations of your instances.
+```json
+{
+	"ip": "<proxmox-ip>",
+	"web_url": "https://<proxmox-ip>:8006",
+	"ssh": {
+		"user": "<ssh-user>",
+		"privkey": "<path-to-ssh-private-key>",
+		"port": <proxmox-ssh-port>
+	},
+	"vm": {
+		"swarm": {
+			"ip": "<swarm-ip>",
+			"ssh": {
+				"user": "<ssh-user>",
+                "privkey": "<path-to-ssh-private-key>",
+                "port": <swarm-ssh-port>
+			}
+		}
+	},
+	"lxc": {
+		"nginx": {
+			"ip": "<nginx-ip>",
+			"web_url": "https://<nginx-ip>",
+			"ssh": {
+				"user": "<ssh-user>",
+                "privkey": "<path-to-ssh-private-key>",
+                "port": <nginx-ssh-port>
+			}
+		}
+	}
+}
+```
+Below an example of a configuration. Of course you must ensure that the user public key has been deployed on the `<ssh-user>` server.
+
+You may notice the configuration has two distincts keys: **vm** and **lxc**. And, obviously, it refers to a virtual machine and a linux container.
+For convience, **Docker Swarm** is installed on a **vm** to ensure a strong isolated environment. If you decided for an LXC, you have to update this section of the code and rebuild the binary:
+```go
+func (hm *HMMap) GetSwarmNetInfo() *HMNetInfo {
+	data, ok := hm.VM["swarm"] // update to hm.LXC["swarm]
+	if !ok {
+		return nil
+	}
+
+	return data
+}
+```
+
+* In your project root directory, create a `.homeserver` directory with a configuration file: `hmdeploy.json`:
+```json
+{
+    "name": "<project-name>",
+    "image": "<project-image-name>:<project-image-tag>",
+    "dependencies": {
+        "env": "<project-dot-env-path>",
+        "compose": "<project-docker-compose-path>",
+        "nginx": "<project-nginx-conf-path>"
+    }
+}
+```
+The filepaths can be absolute or relative. If the filename is only mentionned, it assumes the corresponding files are inside the `.homeserver` dir of your project.
+
+The **image**, **env** and **nginx** fields are optionals.
+If you have a Docker registry with the target image available, you can thus leave image empty. It is used if you want to push a local image or don't have a docker registry.
+
+## Run
+
+> **NOTE**: You need to have a **Go toolchain >= 1.22** installed in order to install/run the binary.
+
+* Clone the repository
+```bash
+git clone https://gitea.thegux.fr/rmanach/hmdeploy
+```
+* Install the binary
+```bash
+make install
+```
+The binary is then installed in your **$GOPATH/bin**.
+
+* Run it !
+```bash
+# if your are in the project dir with a `.homeserver`
+# you can then launch the program directly
+hmdeploy
+
+# if you want the deploy a specific project
+# use --path to point the project dir where `.homeserver` is located
+hmdeploy --path /path/my-project
+```
+
+## Next steps
+* Improve the CLI arguments
+* We'll see...