Skip to main content

Deployment Script

The deployment system is the main feature in DOM Cloud. It let's you to perform automatic configuration all by convenience of a single script. It's also can be used as a CI (Continous Integration) tool that perform some tasks inside your website.

This page is meant for average technical user which already understand how SSH and linux commands works in a basic way. If not, please start from Getting Started and General NGINX Guide as we have a plenty of existing deployment templates. If you need to customize it, learn how SSH works first from other resources or ask someone to help you.

The deployment system is accessible through Setup -> Deploy tab in the navigation once inside a website.

The buttons explained:

  • Add a deployment task: Add a new deployment task as we will describe through this page.
  • Debug Manually: This opens the editor menu to let you open SSH/Filestash and do tasks manually.
  • Start Over: Open a dialog to let you create a new template or upload new apps here like in the create tab.

For common script deployments, there's existing recipes from the deployment page or recipe repository.

We try to make it as simple as possible to understand. We also make our backend processing open sourced so you take a better view of how it works if you want that.

The script runner is in YAML format. Here's a simple overview:

source: # Source URL to replace all files in "public_html"
features: # List of features to be enabled or configured
nginx:  # NGINX configuration to be set for current website
commands: # List of SSH commands that will be executed inside "public_html"

Each of these keys are explained in details below.

source​

Source URL from internet to replace all files in ~/public_html. Common examples:

# Clones octocat.github.io to  "~/public_html"
source: https://github.com/octocat/octocat.github.io
# Download latest WordPress and extracts it from "wordpress" folder
source: 
  url: https://wordpress.org/latest.zip
  directory: wordpress
# Removes all files and directories in "~/public_html"
source: clear

Type: string or object. If it a string, it will be the url.

If this value is set, it will download contents inside the host. The content can be either a ZIP file or a Git repository (to perform clone), or clear to simply clears the content.

tip

This option is useful if your files is already in a public repository such as GitHub. If you need to upload the files from your local device use Webmin File Manager.

danger

This option will always overwrite all contents inside the host. Use with caution!

url​

The zip (or clone) URL to download. Required.

type​

To extract a ZIP file or clone a repo. If omitted, it autodetects whether it is a github.com or gitlab.com URL and perform clone instead of extract.

directory (type: extract only)​

Specify the folder name to move out of ZIP file after extraction. This also can be specified from url's hash. If omitted, no move operation performed.

For legacy reason, a directory in root config will works too, it will be converted as source.directory.

branch (type: clone only)​

Specify the clone branch to get checked out. This also can be specified from directory or url's hash. If omitted, the default branch is checked out.

shallow (type: clone only)​

Do shallow clone? Default to true. It is recommended to leave it that way to keep .git internal size low.

submodules (type: clone only)​

Do Recursive clone of submodules? Default to false.

features​

Enable, configure or disable one or more features in the website. Common examples:

# Enable MariaDB and PostgreSQL and Valkey
features:
- mysql
- postgresql
- valkey
# Install latest Node.js and Python in the server
features:
- node
- python
# Ask for a new TLS certificate from let's encrypt
features:
- ssl

Type: Array of string or object. If one item is a string, it will be converted to object (.e.g. mysql on become { mysql: on }).

This configures all features available for the host in DOM Cloud.

mysql​

Configure MariaDB (MySQL-like) Database Server.

  • mysql or mysql on Enable MariaDB and create default DB.
  • mysql create <dbname> Create a new database with <username>_<dbname>.
  • mysql drop <dbname> Drop a database with <username>_<dbname>.
  • mysql off. Disables mysql feature. Caution: Also drop all DB permanently.

postgresql​

Configure PostgreSQL Database Server.

  • postgresql or postgresql on Enable PostgreSQL and create default DB.
  • postgresql create <dbname> Create a new database with <username>_<dbname>.
  • postgresql drop <dbname> Drop a database with <username>_<dbname>.
  • postgresql off. Disables postgresql feature. Caution: Also drop all DB permanently.

redis​

Configure Valkey (Redis-like) Database Server.

  • redis or redis on Enable Valkey and create default DB.
  • redis create <dbname> Create a new database with <username>_<dbname>.
  • redis drop <dbname> Drop a database with <username>_<dbname>.
  • redis off. Disables redis feature. Caution: Also drop all DB permanently.

dns​

Configure BIND DNS Server.

  • dns or dns on Enable DNS server.
  • dns add <type> <value> Add a record.
  • dns rem <type> <value> Deletes a record.
  • dns off. Disables dns feature. Caution: Also clears all DNS records.

You can add multiple records with lists. For example:

features:
- dns:
  - add a sub-a 1.2.3.4
  - add aaaa sub-a 2001:1:2:3:4:5:6:7
  - add cname sub-b example.net.
  - add cname sub-c example.net.

DNS records for child server is handled automatically.

info

When applying CNAME, looks out for the trailing dot (.) at the end of CNAME values.

It is required to specify the root domain, otherwise it will be appended with the parent domain.

tip

DNS records is also configurable via Webmin DNS.

firewall​

Configure outgoing firewall in your domain. Only configurable for users with Lite plan or above.

  • firewall on or firewall Enable firewall (default for free users).
  • firewall off Disable firewall (default for subscribing users).

Firewall is an additional protection to make sure the host won't send any outgoing request not defined in the whitelist.

See the relevant security description regarding this feature.

ssl​

Configure SSL or Attempt to renew SSL certificate with Let's Encrypt.

  • ssl, renew SSL certificate with shared domain (if available) or using Let's Encrypt if it not exists yet or starts to expire.
  • ssl letsencrypt, renew SSL certificate with Let's Encrypt forcibly.
  • ssl selfsign, renew SSL certificate with Self-signed certificate forcibly.
  • ssl always Always redirect HTTP to HTTPS
  • ssl on Enable both HTTP to HTTPS
  • ssl off Disable HTTPS access (not recommended)

http​

Configure HTTP version for HTTPS.

  • http 1 use HTTP version 1
  • http 3 use HTTP version 3

Using HTTP version 3 can be much faster.

root​

Set directory root path. This also changes the root directive in NGINX config.

info

root is configurable both in features: and nginx:. The following is equivalent:

features:
- root: public_html/public
nginx:
  root: public_html/public

docker​

Configure Docker capability. Only for users with Kit and Pro plan.

  • docker on or docker Enable docker.
  • docker off Disable docker.

With this enabled it doing three things:

  • usermod --add-subuids --add-subgids $USERNAME to allow docker rootless using sub uids for assigning containers.
  • loginctl enable-linger $USERNAME to allow processes not get killed when SSH session terminates.
  • dockerd-rootless-setuptool.sh install to install docker daemon in user-scope.

The docker CLI is always available regardless of this settings as this is provided from a system-wide install packages. Read more on how to deploy with docker.

neovim​

Installs Neovim NvChad. This simply run git clone https://github.com/NvChad/starter ~/.config/nvim. After this installed, run nvim in terminal and type :MasonInstallAll to install missing neovim packages. Read more about Neovim with NvChad.

dnf​

Installs additional packages similar to OS-wide dnf install

php​

Set PHP (FastCGI) version. Available options:

  • php 7.4
  • php 8.1
  • php 8.2
  • php 8.3
  • php latest (default)

Remember that php 8.x is an active release. Changing this version also sets the php (and composer) to the right version in CLI/SSH.

PHP files that served through NginX are served with php-fpm (FastCGI Process Manager).

You can't install custom PHP versions or any PHP modules since these are installed by RHEL system packages. However if you're expert enough you can install a PHP binary yourself then use Passenger Phusion GLS to run PHP by FastCGI. Read more on how to deploy PHP websites.

node​

Install specific NodeJS version. Available options:

  • node or node latest
  • node lts
  • node beta
  • node x.y.z
  • node off

By default it's Node 20.x provided from RHEL system packages. Note that the default system doesn't provide Corepack and supplemental package managers like yarn (berry version) or pnpm.

This also sets the node (and npm, yarn, etc.) to the right version in CLI/SSH and corepack will enabled. This installation is powered by nvm. All given node version is downloaded in binary/compiled version from the official registry to keep switching version fast. Read more on how to deploy Node apps.

python​

Install specific Python version. Available options:

  • python or python latest
  • python lts or python stable
  • python system
  • python x.y
  • python x.y.z
  • python off

By default it's Python 3.9 provided from RHEL system packages, equivalent with python system.

This also sets the python (and pip) to the right version in CLI/SSH. This installation is powered by pyenv. If binary version is available then it will use it to make switching fast.

If you have problem creating virtual envs please using pyenv virtualenv or just use version python system which also works and always isolated for current user.

The difference with python system and python off is the latter will remove pyenv and all former local python installations.

The installer will try to download binary/compiled version from community builds if available to keep switching version fast. Read more on how to deploy Python apps.

ruby​

Install specific Ruby version. Available options:

  • ruby or ruby latest
  • ruby lts or ruby stable
  • ruby x.y.z
  • ruby trufferuby
  • ruby off

By default it's Ruby 3.0 provided from RHEL system packages. All instalations with ruby gems has --no-document implied from global settings to keep installation minimal and fast.

This installation is powered by rvm. It will try to download compiled version from custom RVM builds if available to keep switching version fast. Read more on how to deploy Ruby apps.

deno​

Install specific Deno version. Available options:

  • deno or deno latest
  • deno beta
  • deno x.y.z
  • deno off

There's no Deno installed in system-wide binaries. You must specify this feature to make it available.

This installation is powered by webi. Read more on how to deploy Deno apps.

bun​

Install specific Bun.js version. Available options:

  • bun or bun latest
  • bun x.y.z
  • bun off

There's no Bun.js installed in system-wide binaries. You must specify this feature to make it available.

When configuring NGINX with bun you have to prefix it with proxfix which is installed by default.

This installation is powered by webi. Read more on how to deploy Bun.js apps.

go​

Install specific Go version. Available options:

  • go or go latest
  • go x.y.z
  • go off

There's no Go installed in system-wide binaries. You must specify this feature to make it available.

This installation is powered by webi. Read more on how to deploy Go apps.

rust​

Install specific Rust version. Available options:

  • rust or rust latest
  • rust x.y.z
  • rust off

There's no Rust installed in system-wide binaries. You must specify this feature to make it available.

This installation is powered by rustup. It will install minimal profile to keep switching versions fast. Read more on how to deploy Rust apps.

java​

Install specific Java version. Available options:

  • java or java latest
  • java stable or java lts
  • java x.y.z
  • java off

There's no Java installed in system-wide binaries. You must specify this feature to make it available.

This installation is powered by Adoptium Project. Only latest build from them in each major version (as low as jdk 8) is available to download using this feature. Read more on how to deploy Java apps.

dotnet​

Install specific .NET Core version. Available options:

  • dotnet or dotnet latest
  • dotnet x.y.z
  • dotnet off

There's no .NET Core installed in system-wide binaries. You must specify this feature to make it available.

This installation is powered by Microsoft .NET Core builds. Only versions provided by them is available to install. Read more on how to deploy .NET Core apps.

zig​

Install specific Zig version. Available options:

  • zig or zig latest
  • zig beta
  • zig x.y.z
  • zig off

There's no Zig installed in system-wide binaries. You must specify this feature to make it available.

This installation is powered by webi. Read more on how to deploy Zig apps.

nginx​

Configures NGINX for a given website. Can be a string or object. If passed as string, it will be converted into YAML object before config gets applied. You are only allowed to change NGINX properties based on what YAML object can permits.

Common examples:

# Standard NGINX setup for PHP framework 
nginx:
  root: public_html/public
  fastcgi: on
  locations:
  - match: /
    try_files: $uri $uri/ /index.php$is_args$args
# Standard NGINX setup for Node.js via GLS
nginx:
  root: public_html/public
  passenger:
    enabled: on
    app_start_command: env PORT=$PORT node server.js
# Standard NGINX setup for Python through WSGI
nginx:
  root: public_html/public
  passenger:
    enabled: on
    python: .pyenv/shims/python
features:
  - python # This install python to .pyenv/shims/python
commands:
  - echo "from app import app as application" > passenger_wsgi.py

All configurations below are not preserved at each config update. It's recommended to use the NGINX tab in the dashboard to reconfigure NGINX.

fastcgi​

Whether to enable or not enable PHP file execution: on, always or off. If omitted, off is the default.

tip

Read more about fastcgi option in Deployment for PHP.

error_pages​

List of error pages command. It's particularly useful for static websites. Read on the NGINX docs.

  • 404 /404.html: Show 404 error page as 404.html.
  • 404 =200 /200.html: Assume 404 error as 200 OK and show 200.html (SPA).
  • 500 502 503 504 /50x.html: Show 50x error as 50x.html.

passenger​

If you want to run Non-PHP apps, you need to setup with Passenger Phusion. Passenger is an additional layer on top of NGINX to run any non-PHP apps.

To enable non-PHP apps, at minimum you need these configuration:

root: public_html/public
nginx:
  passenger:
    enabled: on
    app_start_command: node server.js --port=$PORT

The configuration above will execute node server.js --port=$PORT in the parent of root folder (in this case, ~/public_html). Note that you always need to pass the $PORT and use that as the port where your app is listening to. If your app accept port from environment instead you can use env like env PORT=$PORT node server.js.

For custom environment values you can leverage app_env and env_var_list.

To restart a non-PHP apps you can execute restart in CLI/SSH. You can also make it always restart if you have to.

Available options:

  • enabled: on or off (default)
  • app_env: environment setup. Either production (default) or development.
  • env_var_list: array of environment values in the format of KEY=VALUE.
  • set_header_list: array of header values in the format of KEY=VALUE.
  • app_start_command: Passenger GLS command to start the app with $PORT as the port where your app is listening to.
  • friendly_error_pages: on (default) or off
  • base_uri: base URL for the app (default is /).
  • document_root: path to public document root (default is root) (relative to $HOME).
  • app_root: path to app root (default is parent of root) (relative to $HOME).

For non-GLS (an alternative way if not using app_start_command) these options are available too:

  • app_type: Type of App
  • startup_file: Startup filename.
  • ruby: Path to Ruby executable (relative to $HOME).
  • nodejs: Path to Node.JS executable (relative to $HOME).
  • python: Path to Python executable (relative to $HOME).
  • meteor_app_settings: Path to Meteor app settings (relative to $HOME).
tip

Read more about passenger option for general app in NGINX and App daemon.

locations​

Array objects which one or more of:

  • match: Matching URL location (required)
  • root: Root path (relative to $HOME)
  • alias: Alias path (relative to $HOME)
  • rewrite: Rewrite URL directive
  • try_files: Try files URL directive
  • return: Return code directive
  • fastcgi: (same as above)
  • passenger: (same as above)
  • proxy_pass: Proxy to 127.*.*.*:* or unit or docker:*

Please read NGINX Location directive for more information.

unit​

Type: object

NGINX Unit is a newer polyglot alternative to passenger features much simpler deployment system, logging and persistent instance across NGINX reload. The use of unit is much recommended albeit experimental.

NGINX Unit can bind to NGINX via proxy_pass: unit directive, then the app must listen to IPv4 localhost (127.0.0.1) and $PORT env much like how Passenger GLS works. This is the minimal settings to make it works:

nginx:
  root: public_html/public
  proxy_pass: unit
unit:
  # Bun.serve() always listen to $PORT
  app_start_command: bun .

Available options:

  • app_start_command (required) a string command equivalent with how would you run the app in SSH/bash
  • app_root (optional) a string path of app working directory (defaults to public_html)
  • env_var_list (optional) array of header values in the format of KEY=VALUE

commands​

Type: array of string or object.

List of SSH commands in sequence. The starting directory is always ~/public_html. If any exit code detected to be not zero, the execution chain stop.

This is where all the terminal commands written, for example to install depedencies, compiling binaries or injecting database credential.

The list of commands is always executed after the source and features and before nginx.

If array item is object, it can be:

  • command: Nothing different with passing string directly
  • feature: One of feature need to be run at the sequence
  • services: One of services need to be run at the sequence
  • filename and content: Do echo $CONTENT > $FILENAME

services​

Type: string or object.

Aids in compose file management for docker. If passed as string, the compose file will read from given filename. Otherwise, The services object is used as the YAML script for compose file.

Passing string as the compose filename is recommended as you can also define volumes and networks in compose file.

The compose file is read, then modified, then saved back to given filename or docker-compose.yml relative to $HOME/public_html. See docker deployment to understand how it works.

Builtin envar for commands​

Aside with the usual SSH commands, it does have an additional envar to help with scripting:

  • $USERNAME: The server username.
  • $DATABASE: The database name (usually ${USERNAME}_db but can be changed if new database name is supplied before).
  • $PASSWORD: The user SSH login password.
  • $MYPASSWD: The user MySQL login password.
  • $PGPASSWD: The user PostgreSQL login password.
  • $DOMAIN: The domain name.

These envars also will be set:

  • CI=true
  • CONTINUOUS_INTEGRATION=true
  • LANG=en_US.UTF-8
  • LC_ALL=en_US.UTF-8
  • PIP_PROGRESS_BAR=off
  • BUILDKIT_PROGRESS=plain

These shell extras also be set:

  • unset HISTFILE TERM
  • shopt -s dotglob

Time limit​

The time limit for overall script in single run is 15 minutes. If it's exceeded, the execution chain will automatically stop by signaling both SIGTERM and SIGKILL.

subdomains and subdomain​

subdomains is used to run specific commands for a given subdomain name. It's an array of objects with subdomain, some of the features and commands keys. Here's specific example to do it:

subdomain: mysubapp
features:
- mysql # creates mysql db for mysubapp.<domain>
subdomains: 
- subdomain: mysubapp
  features:
  - mysql # creates mysql db for mysubapp.<domain>
- subdomain: mysubweb
  features:
  - mysql  # creates mysql db for mysubweb.<domain>

When subdomains are used, some definitions such as source, nginx, features and commands is adjusted to apply for a given subdomain name, including changing the root execution to ~/domains/<subdomain_name>/public_html instead of ~/public_html.