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.
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 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.
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.
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 assource.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
ormysql 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
. Disablesmysql
feature. Caution: Also drop all DB permanently.
postgresql
Configure PostgreSQL Database Server.
postgresql
orpostgresql 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
. Disablespostgresql
feature. Caution: Also drop all DB permanently.
dns
Configure BIND DNS Server.
dns
ordns on
Enable DNS server.dns add <type> <value>
Add a record.dns rem <type> <value>
Deletes a record.dns off
. Disablesdns
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.
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.
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
orfirewall
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 HTTPSssl on
Enable both HTTP to HTTPSssl off
Disable HTTPS access (not recommended)
http
Configure HTTP version for HTTPS.
http 1
use HTTP version 1http 2
use HTTP version 2
Using HTTP version 2 can be faster and beneficial on some websites.
root
Set directory root path. This also changes the root
directive in NGINX config.
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
ordocker
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
ornode 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
orpython latest
python lts
orpython 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
orruby latest
ruby lts
orruby stable
ruby x.y.z
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 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
ordeno 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
orbun 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
orgo 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
orrust 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
orjava latest
java stable
orjava 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
ordotnet 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
orzig 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.
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
: Show404
error page as404.html
.404 =200 /200.html
: Assume404
error as 200 OK and show200.html
(SPA).500 502 503 504 /50x.html
: Show50x
error as50x.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
oroff
(default)app_env
: environment setup. Eitherproduction
(default) ordevelopment
.env_var_list
: array of environment values in the format ofKEY=VALUE
.set_header_list
: array of header values in the format ofKEY=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) oroff
base_uri
: base URL for the app (default is/
).document_root
: path to public document root (default isroot
) (relative to$HOME
).app_root
: path to app root (default is parent ofroot
) (relative to$HOME
).
For non-GLS (an alternative way if not using app_start_command
) these options are available too:
app_type
: Type of Appstartup_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
).
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 directivetry_files
: Try files URL directivereturn
: Return code directivefastcgi
: (same as above)passenger
: (same as above)proxy_pass
: Proxy to127.*.*.*:*
orunit
ordocker:*
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/bashapp_root
(optional) a string path of app working directory (defaults topublic_html
)env_var_list
(optional) array of header values in the format ofKEY=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 directlyfeature
: One of feature need to be run at the sequenceservices
: One of services need to be run at the sequencefilename
andcontent
: Doecho $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 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
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.
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
.