144 lines
4.9 KiB
Markdown
144 lines
4.9 KiB
Markdown
# 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
|
|
{
|
|
"swarm": {
|
|
"ip": "<swarm-ip>",
|
|
"ssh": {
|
|
"user": "<ssh-user>",
|
|
"privkey": "<path-to-ssh-private-key>",
|
|
"port": <swarm-ssh-port>
|
|
}
|
|
},
|
|
"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.
|
|
|
|
* In your project root directory, create a `.homeserver` directory with a configuration file: `hmdeploy.json`:
|
|
```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
|
|
```bash
|
|
git clone https://gitea.sonak.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:
|
|
-config string
|
|
define the configuration directory (default "/home/<user>/.homeserver")
|
|
-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
|
|
-no-swarm
|
|
no Swarm 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
|