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

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

{
	"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": "my-api",
    "dependencies": {
        "swarm": {
            "env": ".env",
            "compose": "docker-compose.deploy.yml",
			"images": ["my-local-image:tag"]
        },
        "nginx": {
            "conf": "nginx.conf",
            "assets": "assets/"
        }
    }
}

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.

All dependencies fields are optionals. If you don't need swarm skip it, if you don't need .env skip it, if you don't nginx... You see the trick. If you have a Docker registry with the target image available, you can thus leave images field 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 !

hmdeploy --help
Usage of hmdeploy:
  -confirm
        do not ask for confirmation, you're the best, you don't need confirmation
  -debug
        show debug logs
  -destroy
        delete the deployed project
  -details
        extract swarm details and return
  -no-nginx
        no Nginx deployment
  -path string
        define the .homeserver project root dir (default ".")
  -version
        show program version and return
		
# 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
• Check deployment/undeployment state
• Create a deployment temp dir (lock to avoid concurrent deployments)
• Deals with bugs
• Tests 😮‍💨

Contact

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