The Docker Host is a service to create and manage UIX App containers as portable Docker containers used for UIX app deployment. Remote containers are created via DATEX interface on the Docker Host.
Warning
Docker Hosts are only support on Linux systems. If you experience some issues with your Linux distribution please let us know.
Make sure to have git
, Docker
and unzip
installed on your machine and available on the system path.
You can setup your personal Docker Host on the target machine using the following command:
curl -s https://raw.githubusercontent.com/unyt-org/docker-host/main/setup.sh | bash -s @+YOUR_DOCKER_HOST
Make sure to pass a unique endpoint id to the install script. The setup script will create a Docker Host instance by installing Deno and creating a persistent service inside of etc/systemd/system
.
Make sure that the service is up and running:
systemctl status unyt_YOUR_DOCKER_HOST
The config.dx
file is used to apply custom configuration to the Docker Host:
{
token: "ACCESS_TOKEN",
enableTraefik: false,
hostPort: 80,
allowArbitraryDomains: true,
setDNSEntries: false
}
- token - If an access token is configured, the Docker Host will deploy apps only if they have the correct token configured. It is highly recommended to use a strong access token if the Docker Host is used for personal deployment only.
- enableTraefik - If enabled, a Traefik Proxy is installed automatically to act as reverse proxy on your system to handle different domains and automatic SSL. If this option is disabled, you have to make sure to handle the routing of HTTP traffic to your personal container by yourself.
- hostPort - Configure the Docker port to expose traefik on.
- allowArbitraryDomains (internal) - Allow arbitrary domains to be configured. If set to false, only *.unyt.app-domains can be used for deployment.
- setDNSEntries (internal) - If you have access to the unyt.org DNS service, you can enable this option to allow for *.unyt.app-domains.
To reload the configuration, the service must be restarted using the following command:
systemctl restart unyt_YOUR_DOCKER_HOST
Your UIX app is automatically deployed to the Docker Host if the location
option in the backend/.dx
file is set to the Docker Host endpoint. Please refer to the Deployment Documentation for more details.
The location can be customized for specific stages:
use stage from #public.uix;
location: stage {
staging: @+YOUR_STAG_HOST,
prod: @+YOUR_PROD_HOST
}
You can configure custom (sub)-domains to be used by your app for different stages:
domain: stage {
staging: "staging.example.com",
prod: "example.com"
}
You can configure custom endpoints to be used as your app backend endpoints within different stages:
endpoint: stage {
staging: @+example-stage,
prod: @+example
}
Warning
If the Docker Host you plan to deploy to has a access token configured, you need to pass this access token to UIX to make sure your app can authenticate.
You can set the access token as HOST_TOKEN
environment variable on your local UIX projects console.
export HOST_TOKEN=YOUR_TOKEN
To deploy your UIX app, please make sure you have the latest changes in sync with your remote git repository. This is required by the Docker Host, since it will clone your sources via GitHub or GitLab API on deployment.
To deploy your app, start uix
via CLI. If you want to select a custom stage pass the --stage <name>
argument.
uix --stage prod
Above command will select the location configured for the prod
-stage and deploy your app:
- Host:
@+YOUR_PROD_HOST
- Domain:
example.com
- Endpoint:
@+example
Warning
Git Deployment is only support for GitHub and GitLab including self-hosted option.
The git_deploy plugin can be configured in your app.dx
file to automate deployment:
plugin git_deploy (
// Deploy this app in the 'prod' stage
// when a push to the main branch occurs
// The 'MY_SECRET_TOKEN' GitHub secret is passed as an
// environment variables to the UIX app
prod: {
branch: 'main',
on: 'push',
secrets: ['MY_SECRET_TOKEN']
}
)
The git_deploy
plugin takes an object where the keys are the stage names and the values are an object with the following options:
branch: (text or text[])
- One or more branches on which the deployment is triggeredon: (text or text[])
- GitHub event name that triggers the deploymentsecrets (text or text[])
- List of GitHub secrets that are exposed to the app as environment variablestests: (boolean)
- If this option is enabled, tests for all*.test.ts
,*.test.js
and*.test.dx
files in the repository are automatically executed before deployment (enabled per default)
Make sure to run the uix
command locally before commiting the changes to the remote repository, since when the git_deploy
plugin is defined, all GitHub workflow files are generated automatically when the app is run.
Warning
If the Docker Host you plan to deploy to has a access token configured, you need to configure the HOST_TOKEN
as GitHub/GitLab actions secrets for your repository.
You can use DATEX to interact with the ContainerManager
interface for your Docker Host.
use ContainerManager from @+YOUR_DOCKER_HOST;
ref container = ContainerManager.createUIXAppContainer(
"HOST_TOKEN", // Optional access token if configured so
"git@github.com:benStre/xam.git", // git origin for the UIX app
"main", // branch name
@+my_app_deployment, // endpoint for the deployment stage
"prod", // stage
["my-app.com"], // custom exposed domains
["SECRET=123", "SECRET2=42"] // environment variables
);
print container.status // current container status
Workbench container might be helpful for development.
use ContainerManager from @+YOUR_DOCKER_HOST;
container = ContainerManager.createWorkbenchContainer("HOST_TOKEN");
container.start()
© unyt 2024 • unyt.org