This document presents an example of the container-hosted setup deployment with OutSystems. The information should be used for internal and testing purposes only. We assume that the readers are familiar with the referenced technologies.
The automation process as show in this document guarantees that a container is running with the deployed OutSystems application and creates the rewrite rules that ensure the container is reachable from "the outside".
You should read the documentation about containers in OutSystems. In particular, the parts about network and deployment zones and publishing to a Docker container.
1. Set up the servers
To follow the instructions, you need two servers with IIS as the reverse proxy (OutSystems Machine + Containers Machine with IIS as the reverse proxy), or three if you want to use NGINX as the reverse proxy (OutSystems Machine + Containers Machine + reverse proxy with NGINX).
- Windows Server 2016
- OutSystems Platform Server, including sample apps that can be deployed to containers
Reverse proxy option 1 - IIS
This setup requires one additional Windows Server and it's the fastest method to set up a working test scenario. Check the document How to set up IIS as a Reverse Proxy for the instructions.
Reverse proxy option 2 - NGINX
This is a more advanced scenario that provides more scalability and flexibility. It requires two additional servers:
- Windows Server for a Container
- Linux Server for NGINX
Check the document How to set up NGINX as a Reverse Proxy for the instructions.
The deployment scripts
You also need the following two sets of scripts:
- OutSystems Docker automation scripts - the pipelines use them to deploy the apps
- Jenkins pipeline scripts - you use them to configure the pipelines
Check out these repositories in the root folder for this example, which is
2. Configure the file access
The OutSystems Machine needs to be able to write the application bundle and the configurations to two folders and read the result files from the Containers Machine. The simplest way to achieve this is to create the folders locally in the Container Machine and then create a network share of those folders accessible to the OutSystems machine (with, at least, read and write access for the same user as the one running IIS in that machine). You should have these local folders and their network shares:
- The Output Files To (or Target Path): created in
C:\jenkins\bundles, with the network share at
- The Result (or Result Path): created in
C:\jenkins\results, with the network share at
- The Output Config Files To (or Config Path): created in
C:\jenkins\configs, with the network share at
Here is the overview of the result files:
The emphasized parts correspond to the configuration we will perform later. To get more context about the paths, read the section "Configure the Deployment Zone".
3. Copy the Docker automation scripts
Copy the OutSystems automation scripts to
C:\jenkins\ of the Container Machine. The relative paths should remain unchanged. If you place the folders in
<your_custom_folder>, make sure you maintain the folders like this:
<your_custom_folder>\utils and so on.
The scripts are used by the pipelines we will set up soon.
4. Set up Jenkins
These are the basic configuration steps to use Jenkins in our testing deployment scenario.
Ensure that you have 64-bit version of Jenkins running. Go to Manage Jenkins > System Information and verify that the value of the java.vm.name is "64-Bit". If not, you must configure Jenkins to use Java x64 before continuing.
Install the PowerShell plugin by going to Manage Jenkins > Plugin Manager > Available tab, searching for PowerShell, checking and selecting Download now and install after restart.
Allow the build triggers to be called anonymously. Go to Manage Jenkins > Configure Global Security and set Jenkins authorization to Anyone can do anything. This has the advantage of allowing build triggers to be called without additional authorization headers, which is acceptable in our current scenario. However, this level of Access Control option should not be used in production.
Allow your containers to access the OutSystems platform
private.key. The containers need to have a volume where the
private.keyis accessible. Copy it to a suitable location. We assume that the
private.keywas copied to
C:\jenkins\secretsin the Containers Machine. The most likely location of
C:\Program Files\OutSystems\Platform Server.
5. Set up the pipelines
We are going to configure four pipelines, one for each of the Deployment Operations (build, run, remove, update). We start with the configuration that is common to all pipelines, and then provide the details for the individual pipelines.
Create a Folder and name it DockerDeployment. Go to Jenkins > New Item. Select the Folder option, enter a name and click OK. It will be used for all pipelines. This keeps things organized.
Create the pipeline. Navigate to Jenkins > DockerDeployment (in the Builds view). Click New Item, select Pipeline, give it a name relevant to the operation and click OK. We suggest using the names that show the action: ContainerBuild, ContainerRun, ContainerRemove, and UpdateConfigurations.
Add the required parameters: Address, ApplicationName, ApplicationKey, OperationId, TargetPath, ResultPath, ConfigPath and ModuleNames. Check the This project is parameterized option, select Add Parameter and then String Parameter. This enables you to create a parameter for the pipeline. Do this for the remaining parameters. Don't forget to click Apply as you go along to save the changes.
Add the additional parameter HostingTechnology. This sets the Container Automation Module which will be used for the deployment process. Set the Default Value to the one applicable to your specific Reverse Proxy scenario:
DockerEEPlusIISfor IIS or
In the Build Triggers section, tick the Trigger builds remotely (e.g. from scripts) option and enter an Authentication Token. In our example setup you can use anything you like. This is the value used for the token parameter required to call the URL trigger. This is the last step that's common to all the pipelines. Next we add the Pipeline Scripts specific to each pipeline.
The ContainerRun pipeline requires that you add two additional parameters: SecretPath and PlatformServerFQMN. Respectively, these represent the folder local to the Docker machine where you placed the
C:\jenkins\secrets\) and the fully qualified name of the OutSystems machine (e.g site.domain.example.com). Set the Default Value of each of these parameters to what is applicable to your specific scenario.
For each of the four pipelines, in the Pipeline section, have Pipeline script selected. Copy the pipeline script that corresponds to the respective pipeline and paste it into the Script text area, then modify the import path to the applicable to your specific scenario. Click Save.
6. Configure the Deployment Zone
Now that we have our automation infrastructure we can create a deployment zone that makes use of it. Let us review the configuration in Service Center > Administration > Deployment Zones > the Zone name.
- Name - The name you want to give to your deployment zone (e.g. Container Zone)
- Deployment Zone Address - The fully qualified network name of the publicly accessible endpoint of the deployment zone (e.g.
- Output Files To - The network shared folder in the Container Machine where the OutSystems Machine will place the bundles (e.g.
- Result - The network shared folder in the Container Machine where the OutSystems Machine will expect the result files (e.g.
- Output Config Files To - The network shared folder in the Container Machine where the OutSystems Machine will place the config files for the applications (e.g.
- Container Build Trigger URL - The build trigger for the Container Build Jenkins Pipeline we configured (e.g.
- Container Run Trigger URL - The build trigger for the Container Run Jenkins Pipeline we configured (e.g.
- Update Configurations Trigger URL - The build trigger for the Update Configurations Jenkins Pipeline we configured (e.g.
- Container Remove Trigger URL - The build trigger for the Container Remove Jenkins Pipeline we configured (e.g.
7. Test the pipelines
Now that the configuration of Jenkins is finished, try deploying an OutSystems application configured for the deployment zone. You can do it by using Service Center. Check the status of the pipelines in Jenkins > DockerDeployment (following our example). Each build should have a log with more details.