From 655ecf21f4dd3e19972b41456ffc30c1699a3bde Mon Sep 17 00:00:00 2001 From: Mathieu Broillet Date: Mon, 12 Jun 2023 10:13:31 +0200 Subject: [PATCH] update readme doc --- README.md | 193 +++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 141 insertions(+), 52 deletions(-) diff --git a/README.md b/README.md index 1524399..2e75ee7 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,67 @@ Have a look at the resources folder to see how to use it. # Documentation +## Configuration +### Proxmox VE +The Proxmox VE configuration is located in the `config.json` file. +```json5 +{ + "pve":{ + "host": "", + "user": "", // usually root + "port": 22, // ssh port + "local": false // set to true if this program is running directly on the PVE without needing ssh + } +} +``` + +### LXC +To create a LXC, you need to create a JSON file in the `resources/lxc/` folder. +You can look at the example with ID 100 in the `resources/lxc/100` folder. + +Here is an example config with all available parameters : +*Note : this is not valid JSON, it's just for documentation purposes, if you want to copy the file, use the one in the resources folder* +```json5 +{ + "lxc_hostname": "traefik", //hostname of the lxc + + // the os block contains the os type + // alpine | archlinux | centos | debian | devuan | fedora | gentoo | nixos | opensuse | ubuntu | unmanaged + "os": { + "name": "alpine", + "release": "3.17" + }, + + // the resources block contains the resources given to the lxc + "resources": { + "cpu": "2", // number of cpu cores + "memory": "1024", // memory (ram) in MB + "swap": "256", // swap in MB + "disk": "8", // disk size in GB + "storage": "local-lvm" // the proxmox storage to use + }, + + // the network block contains the network configuration + "network": { + "bridge": "vmbr0", // the proxmox bridge to use, vmbr0 is the default one + "ipv4": "dhcp", // ipv4 address, dhcp for dhcp, auto for auto, or an ip address + "ipv6": "auto", // ipv6 address, dhcp for dhcp, auto for auto, or an ip address + "mac": "92:A6:71:77:8E:D8", // mac address, leave empty for random + "gateway4": "", // ipv4 gateway, leave empty for auto/dhcp + "gateway6": "", // ipv6 gateway, leave empty for auto/dhcp + "vlan": "" // vlan id, leave empty for no vlan + }, + + // the options block contains various options for the lxc + "options": { + "privileged": "false", // set to true to run the lxc in privileged mode + "start_on_boot": "false", // set to true to start the lxc on boot + "startup_order": 2, // the startup order of the lxc + "password": "qwertz1234", // the password of the root user, leave empty for none + "tags": "2-proxy+auth" // tags for the lxc to display in the proxmox web ui + }, +``` + ## Creation In the creation section, you have the option to define conditions for checking whether your LXC/VM has been previously configured. If all of these conditions are met, the script will proceed directly to the deploy section and execute the necessary steps to update it. *(This indicates that your LXC/VM has already been configured, and we want to avoid erasing any existing settings/config.)* @@ -22,10 +83,11 @@ However, if **any** of the conditions fail to match, the script will process to ## Conditions ### File The file condition will check if a file exists or not inside the LXC/VM. -```json +```json5 "conditions": { + // use a single file "file": "/var/data/traefikv2/traefik.toml" - or + // or use a list, but only use one "files": ["/var/data/traefikv2/traefik.toml", "/var/data/config/traefikv2/docker-compose.yml"] } ``` @@ -33,10 +95,11 @@ It can be an array of file using ``["file1", "file2"]`` or just one file in doub ### Folder The folder condition will check if a folder exists or not inside the LXC/VM. -```json +```json5 "conditions": { + // use a single folder "folder": "/var/data/traefikv2" - or + // or use a list, but only use one "folders": ["/var/data/traefikv2", "/var/data/config/traefikv2"] } ``` @@ -44,17 +107,39 @@ It can be an array of folders using ``["folder1", "folder2"]`` or just one folde ### Programs The programs condition will check if a program is installed or not in the LXC/VM. -```json +```json5 "conditions": { + // use a single program "program": "docker" - or + // or use a list, but only use one "programs": ["docker", "docker-compose"] } ``` -It can be an array of programs using ``["program1", "program2"]`` or just one program in double quote ``"program"``. - +It can be an array of programs using ``["program1", "program2"]`` or just one program in double quote ``"program"``. *Note:This uses `which` to check if the program matches to anything* +### Command +The command condition will check if a command returns a specific value. +```json +"conditions": { + "command": "whoami", + "value": "root" +} +``` +*Note: This uses `bash -c` to execute the command* +*Note: If value is an integer, it will look for the return code, if it's a string it's check the output.* + +### Docker +The docker condition will check if a docker (or podman) container is running or not. +```json5 +"conditions": { + // use a single container + "container": "traefikv2" + // or use a list, but only use one + "container": ["traefikv2", "portainer"] +} +``` + ## Steps **Note: Paths** @@ -64,71 +149,71 @@ If nothing is specified, the script will use the VM/LXC folder (`resources/lxc/< *The comments in the JSON below are only for documentation purposes and are not valid JSON, remove them before running.* ### Script The script step will execute a script. -```json +```json5 "steps": [ { "type": "script", - "path": "/global/install-docker.sh" # local path (here: resources/scripts/install-docker.sh) + "path": "/global/install-docker.sh" // local path (here: resources/scripts/install-docker.sh) } ] ``` ### File The file step will copy a file to the VM/LXC. -```json +```json5 "steps": [ { "type": "file", - "path": "traefik.toml", # local path (here: resources/lxc//traefik.toml) - "destination": "/var/data/traefikv2/traefik.toml" # lxc/vm path + "path": "traefik.toml", // local path (here: resources/lxc//traefik.toml) + "destination": "/var/data/traefikv2/traefik.toml" // lxc/vm path } ] ``` ### Folder The folder step will copy a folder to the VM/LXC. -```json +```json5 "steps": [ { "type": "folder", - "path": "/data/", # local path (here: resources/lxc//data/) - "destination": "/var/data/traefikv2" # lxc/vm path + "path": "/data/", // local path (here: resources/lxc//data/) + "destination": "/var/data/traefikv2" // lxc/vm path } ] ``` ### Command The command step will execute a command on the VM/LXC. -```json +```json5 "steps": [ { "type": "command", - "command": "whoami", # command to execute - "working_directory": "/var/data/config/traefikv2" # lxc/vm path + "command": "whoami", // command to execute + "working_directory": "/var/data/config/traefikv2" // lxc/vm path } ] ``` ### Docker The docker step will execute a docker command on the VM/LXC. -```json +```json5 "steps": [ { "type": "docker", - "command": "run -d --name=traefikv2 --restart=always -p 80:80 -p 443:443 -p 8080:8080 -v /var/data/traefikv2:/etc/traefik -v /var/data/config/traefikv2:/config -v /var/run/docker.sock:/var/run/docker.sock traefik:latest", # docker command to execute - "working_directory": "/var/data/config/traefikv2" # lxc/vm path + "command": "run -d --name=traefikv2 --restart=always -p 80:80 -p 443:443 -p 8080:8080 -v /var/data/traefikv2:/etc/traefik -v /var/data/config/traefikv2:/config -v /var/run/docker.sock:/var/run/docker.sock traefik:latest", // docker command to execute + "working_directory": "/var/data/config/traefikv2" // lxc/vm path } ] ``` ### Docker-compose The docker-compose step will execute a docker-compose command on the VM/LXC. -```json +```json5 "steps": [ { "type": "docker-compose", - "command": "up -d", # docker-compose command to execute - "working_directory": "/var/data/config/traefikv2" # lxc/vm path + "command": "up -d", // docker-compose command to execute + "working_directory": "/var/data/config/traefikv2" // lxc/vm path } ] ``` @@ -136,12 +221,12 @@ The docker-compose step will execute a docker-compose command on the VM/LXC. ### Git The git step will clone a git repo on the VM/LXC. -```json +```json5 "steps": [ { "type": "git", - "url": "https://git.abc.xyz/abc/abc.git", # git url - "destination": "/root/" # lxc/vm path + "url": "https://git.abc.xyz/abc/abc.git", // git url to clone + "destination": "/root/" // lxc/vm path } ] ``` @@ -149,26 +234,27 @@ The git step will clone a git repo on the VM/LXC. ### Download The download step will download a file on the VM/LXC. -```json +```json5 "steps": [ { "type": "download", - "url": "https://git.abc.xyz/file.tar.gz", # download url - or - "urls": ["https://git.abc.xyz/file1.tar.gz", "https://git.abc.xyz/file2.tar.gz"] # download urls - "destination": "/tmp/" # lxc/vm path + // download a single file + "url": "https://git.abc.xyz/file.tar.gz", // download url + // or use a list of urls, but only use one + "urls": ["https://git.abc.xyz/file1.tar.gz", "https://git.abc.xyz/file2.tar.gz"] // download urls + "destination": "/tmp/" // lxc/vm path } ] ``` ### Extract archive (tar/zip) The unzip step will unzip a file in the VM/LXC. -```json +```json5 "steps": [ { "type": "unzip", - "path": "/tmp/file.tar.gz", # lxc/vm path to the archive - "destination": "/var/data/config/traefikv2" # (optional) lxc/vm path to extract the archive, will use archive parent directory if blank + "path": "/tmp/file.tar.gz", // lxc/vm path to the archive + "destination": "/var/data/config/traefikv2" // (optional) lxc/vm path to extract the archive, will use archive parent directory if blank } ] ``` @@ -176,13 +262,14 @@ The unzip step will unzip a file in the VM/LXC. ### Install package The install-package step will install a package on the VM/LXC. -```json +```json5 "steps": [ { "type": "install-package", - "package": "git" # package to install - or - "packages": ["git", "docker"] # packages to install + // install a single package + "package": "git", + // or use a list of packages, but only use one + "packages": ["git", "docker"] } ] ``` @@ -191,13 +278,14 @@ The install-package step will install a package on the VM/LXC. ### Remove package The remove-package step will remove a package on the VM/LXC. -```json +```json5 "steps": [ { "type": "remove-package", - "package": "git" # package to remove - or - "packages": ["git", "docker"] # packages to remove + // remove a single package + "package": "git" + // or use a list of packages, but only use one + "packages": ["git", "docker"] } ] ``` @@ -216,16 +304,17 @@ The reboot step will reboot the VM/LXC. ### Replace in file The replace-in-file step will replace a string in a file. -```json +```json5 "steps": [ { "type": "replace-in-file", - "path": "/var/data/config/traefikv2/traefik.toml", # lxc/vm path to the file - or - "paths": ["/var/data/config/traefikv2/traefik.toml", "/var/data/config/traefikv2/traefik2.toml"] # lxc/vm paths to the files - "search": "abc", # string to search - "replace": "xyz" # string to replace + // replace in a single file + "path": "/var/data/config/traefikv2/traefik.toml", // inside lxc/vm + // or use a list of files, but only use one + "paths": ["/var/data/config/traefikv2/traefik.toml", "/var/data/config/traefikv2/traefik2.toml"] // inside lxc/vm + "search": "abc", // string to search + "replace": "xyz", // string to replace + "case_sensitive": true, // (optional) case sensitive? default: true } ] -``` - +``` \ No newline at end of file