Deployment System

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.

The deployment system is accessible through Deploy tab in the website menu.

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 from internet to replace all files in "public_html"
features: # List of features to be enabled or configured or disabled
nginx:  # NGINX configuration to be set for current website
commands: # List of terminal 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 MySQL and PostgreSQL
features:
- mysql
- postgresql

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

`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 Whitelist Firewall.

firewall on or firewall Enable firewall.
firewall off Disable firewall.

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 2 use HTTP version 2

`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 (podman) capability. Only for users with Pro plan.

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

With this enabled it changes two things:

usermod --add-subuids --add-subgids $USERNAME to allow podman rootless using sub uids for assigning containers.
loginctl enable-linger $USERNAME to allow processes not get killed when SSH session terminates.

The podman CLI is always available regardless of this settings as this is provided from a system-wide install packages.

`php`

Set PHP (FastCGI) version. Available options:

php 7.4
php 8.0
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.

`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 18.x provided from RHEL system packages.

This also sets the node (and npm, yarn, etc.) to the right version in CLI/SSH. This installation is powered by webi. All given node version is downloaded in binary/compiled version from the official registry to keep switching version fast.

`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 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 requested version is available to keep switching version fast.

`ruby`

Install specific Ruby version. Available options:

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

By default it's Ruby 3.0 provided from RHEL system packages. This installation is powered by rvm. The installer will try to download binary/compiled version from RVM builds if requested version is available to keep switching version fast.

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

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

This installation is powered by webi.

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

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

`java`

Install specific Java version. Available options:

java or java latest
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.

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

`zig`

Install specific Zig version. Available options:

zig or zig latest
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.

`nginx`

Configures NGINX for a given website. 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 passenger-config restart-app / 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). This value is relative to the user $HOME folder.
app_root: path to app root (default is parent of root). This value is relative to the user $HOME folder.

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
nodejs: Path to Node.JS executable
python: Path to Python executable
meteor_app_settings: Path to Meteor app settings

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)

Please read NGINX Location directive for more information.

info

proxy_pass, although it's popular, it's not allowed because it's not a good practice to use it in a shared servers. If you have to redirect TCP connections you can also use socat.

`commands`

Type: array of string.

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.

Builtin envar for commands

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

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

These envars also will be set:

CI=true
CONTINUOUS_INTEGRATION=true
DEBIAN_FRONTEND=noninteractive
LANG=en_US.UTF-8
LC_ALL=en_US.UTF-8

Builtin Git Credentials

If you have logged in with GitHub with repo access, an envar $GITHUB_TOKEN will be available for you to use. Together with Git Credentials API, it will grant the access to your private repos along with all git commands run from the Runner.

This is useful for cloning or pulling private repos after a webhook is received, for example.

caution

This does have security implication and we have taken some security measures to prevent leaks. For example, since it's provided within envar, you git commands will break if run within SSH. That's because its doesn't saved anywhere in the server.

We doesn't prevent you, for example to run echo $GITHUB_TOKEN in the commands list and use it as the token used for SSH session. But we do recommend you to not do that.

Time limit

The time limit for overall script in single run is 10 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.

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 exection to ~/domains/<subdomain_name>/public_html instead of ~/public_html.

source​

url​

type​

directory (type: extract only)​

branch (type: clone only)​

shallow (type: clone only)​

submodules (type: clone only)​

features​

mysql​

postgresql​

dns​

firewall​

ssl​

http​

root​

docker​

php​

node​

python​

ruby​

deno​

bun​

go​

rust​

java​

dotnet​

zig​

nginx​

fastcgi​

error_pages​

passenger​

locations​

commands​

Builtin envar for commands​

Builtin Git Credentials​

Time limit​

subdomains and subdomain​

`source`

`url`

`type`

`directory` (`type: extract` only)

`branch` (`type: clone` only)

`shallow` (`type: clone` only)

`submodules` (`type: clone` only)

`features`

`mysql`

`postgresql`

`dns`

`firewall`

`ssl`

`http`

`root`

`docker`

`php`

`node`

`python`

`ruby`

`deno`

`bun`

`go`

`rust`

`java`

`dotnet`

`zig`

`nginx`

`fastcgi`

`error_pages`

`passenger`

`locations`

`commands`

Builtin envar for commands

Builtin Git Credentials

Time limit

`subdomains` and `subdomain`