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):

+-------------------------+          +-------------------------+            
|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.

{
	"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:

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:

{
    "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

git clone https://gitea.thegux.fr/rmanach/hmdeploy

• Install the binary

make install

The binary is then installed in your $GOPATH/bin.

• Run it !

# 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...