hmdeploy/README.md

# hmdeploy

A tool to deploy a dockerized application with Nginx as reverse proxy.

This tool has been developed for **home server** to deploy Docker image on **Docker Swarm** behind **Nginx** on **Proxmox VE**.
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             |             
|                         |          |                         |             
| +------+    +------+    +----------+                         |<----------- 
| |app1  |    |app2  |    |          |                         | HTTP request
| |      |    |      |    |          |                         |             
| |:8080 |    |:8081 |    |          |                         |             
| +------+    +------+    |          |                         |             
|                         |          |                         |             
|                         |          |                         |             
+-------------------------+          +-------------------------+             
```

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
hmdeploy --help
Usage of hmdeploy:
  -debug
        show debug logs
  -destroy
        delete the deployed project
  -no-nginx
        no Nginx deployment
  -path string
        define the .homeserver project root dir (default ".")
		
# if your are in the project dir with a `.homeserver`
# you can then launch the program directly
hmdeploy

# if you want to deploy a specific project
# use --path to point the project dir where `.homeserver` is located
hmdeploy --path /path/my-project

# if you want to undeploy a specific project
# do not worry, volumes are preserved
hmdeploy --path /path/my-project --destroy
```

## Next steps
* ~~Improve the CLI arguments~~
* ~~Destroy~~
* Post-install script
* Deals with bugs
* Tests 😮‍💨

## Contact
For issues, questions or anything contact me at: admin@thegux.fr