Skip to main content

Enterprise App Store and Testing Distribution in DMZ

Overview​

A Demilitarized Zone (DMZ) in networking is a segment of an internal network that is exposed to external networks, typically over the internet. By isolating Appcircle DMZ server from the internal network, you ensure that it remains secure.

This is particularly useful when users need to access Testing Distribution and Enterprise App Store but not all features for business operations within the private network.

The Testing Distribution module and Enterprise App Store module hosted on the Appcircle DMZ server can be accessed by users from the internet, ensuring they have secure access to these critical features while keeping sensitive business data within your private network. This setup provides a balance between security and productivity in an organization's IT environment.

Screenshot

We assume that you have already set up an Appcircle server successfully. This document will guide you through creating Appcircle DMZ server and Appcircle server configurations.

In this document:

  • We will call the "Appcircle DMZ server" to the server, which is located in the DMZ and host the Appcircle Enterprise App Store and Testing Distribution services.

  • We will call the "Appcircle server" to the server, which is located in the private network and host the Appcircle core services.

info

When you convert to the DMZ architecture, both the Enterprise App Store and the Testing Distribution will be transferred to the Appcircle DMZ server. We currently do not support using only one of them in the Appcircle DMZ server.

Appcircle DMZ Server Pre-requirements​

Below are the hardware and OS requirements for self-hosted Appcircle DMZ server installation.

Supported Linux Distributions​

Self-hosted Appcircle DMZ server, can only be installed on Linux operating system.

If you have installed the Appcircle server with Podman:

  • CentOS Stream 8 or later
  • RHEL 8 or later

If you have installed the Appcircle server with Docker:

  • Ubuntu 20.04 or later
  • Debian 11 or later
  • CentOS 8 or later
  • RHEL 8 or later

Hardware Requirements​

Minimum hardware requirements for self-hosted Appcircle can be:

  • 20GB or more free disk space
  • 4 or more cores CPU
  • 8 or more gigabytes (GB) RAM

☝ These hardware specs are minimum requirements for basic execution and it can be used only for quick evaluation or development purposes.

caution

CPU architecture must be AMD or Intel 64-bit arch (x86_64).

info

If you have enough RAM and a recent CPU, performance of Appcircle server can be limited by hard drive seek times. So, having a fast drive like a solid state drive (SSD) improves runtime.

Higher numbers will be better especially for increased number of users.

For an enterprise installation, minimum hardware requirements are

  • 50GB SSD
  • 8 CPU
  • 16GB RAM

For production environments, recommended hardware requirements are

  • 50GB SSD
  • 32 CPU
  • 64GB RAM
caution

Swap​

Using swap file lets self-hosted Appcircle server exceed the size of available physical memory. On memory pressure system will go on its operations with minimal degradation, when SSD used as hardware.

So, we are recommending swap file usage on Linux.

Its size should be minimum half of the RAM size. For example if you have 64 GB RAM, then you should choose minimum 32 GB swap file size. 64 GB will be better.

Swappiness​

The swappiness parameter configures how often your system swaps data out of RAM to the swap space. So, it's an important setting for swap usage and affects performance.

10 is recommended value for swappiness.

📚 For details on how to configure swap and swappiness parameter, follow guide in here.

Software Requirements​

Container Engine​

You must use the same container engine with on the Appcircle server and the Appcircle DMZ server.

If you have installed the Appcircle server with Podman, you must use Podman on the Appcircle DMZ server.

If you have installed the Appcircle server with Docker, you must use Docker on the Appcircle DMZ server.

Tools​

You need to have the following tools installed on your system:

  • curl
  • tar
  • podman
  • podman-compose

You can install these dependencies from your package repository depending on your distro.

Enabling the Linger Option​

To ensure uninterrupted operation of the Appcircle server's background processes, you must enable the linger option on the host system.

Enabling this option allows the podman containers to persist even after user logouts, ensuring continuous functionality.

Check if the linger option is enabled for the current user with the below command.

loginctl show-user "$USER" --property=Linger

If you see Linger=yes, it means that the option is enabled and you do not need extra configuration.

If the output is Linger=no, this means that the option is disabled and you cannot run the Appcircle server in the background.

caution

If the linger option is set to no, you must enable it to run the Appcircle server in the background.

To enable the linger option, you can use the command below:

loginctl enable-linger

Overcoming Privileged Port Limitations​

When using Podman rootless to install the Appcircle server, please note that privileged ports (ports below 1024) cannot be utilized in rootless mode. By default, the Appcircle server listens on ports 8080 and 8443 for Podman installations.

You must use a port-forwarding tool like socat. This way, you can forward traffic from port 80 to 8080 and from port 443 to 8443.

You should install socat from official repositories and create two systemd services so port forwarding stays even after the server reboot. This can be done by running the following steps:

caution

You must create the socat services below, even if you are using Podman with the root user.

sudo dnf install -y socat

Save the file below as port-redirect-80.service in /etc/systemd/system/ directory.

sudo vi /etc/systemd/system/port-redirect-80.service
[Unit]
Description=Port Redirect Service - Port 80
After=network.target

[Service]
ExecStart=/usr/bin/socat TCP-LISTEN:80,fork,reuseaddr TCP:127.0.0.1:8080

[Install]
WantedBy=multi-user.target

Save the file below as port-redirect-443.service in /etc/systemd/system/ directory.

sudo vi /etc/systemd/system/port-redirect-443.service
[Unit]
Description=Port Redirect Service - Port 443
After=network.target

[Service]
ExecStart=/usr/bin/socat TCP-LISTEN:443,fork,reuseaddr TCP:127.0.0.1:8443

[Install]
WantedBy=multi-user.target

Then, execute the below commands to activate port redirections.

sudo systemctl daemon-reload && \
sudo systemctl enable --now port-redirect-80.service && \
sudo systemctl enable --now port-redirect-443.service

Podman Network Stack​

To ensure successful operation of the Appcircle server, it is required to switch from the CNI network stack to Netavark if Podman is bundled with CNI. You can see your network stack by running:

podman info | grep -i networkBackend

You can switch to Netavark network stack by simply installing Netavark and configure podman to use Netavark.

sudo dnf install -y netavark

Once the installation is complete, please follow these steps to configure Podman:

  • Copy the /usr/share/containers/containers.conf file to /etc/containers/containers.conf.
sudo cp /usr/share/containers/containers.conf /etc/containers/containers.conf
  • Edit the /etc/containers/containers.conf file.
sudo vi /etc/containers/containers.conf
  • Add the following content to the [network] section:
network_backend="netavark"

  • Save the file.

  • Reset Podman:

podman system reset
  • Reboot the system:
sudo reboot
caution

If you skip the step about podman network stack above, you will encounter network related issues. Please make sure you have completed this step.

Firewall Configuration​

If you are using Firewalld, you need to open the ports below according to your server configuration.

  • If you plan to run the Appcircle DMZ server with HTTPS:
sudo firewall-cmd --add-port=80/tcp --permanent
sudo firewall-cmd --add-port=443/tcp --permanent
sudo firewall-cmd --reload
  • If you plan to run the Appcircle DMZ server with HTTP:
sudo firewall-cmd --add-port=80/tcp --permanent
sudo firewall-cmd --reload

To check if the ports are open, you can run the following command:

sudo firewall-cmd --list-ports

SELinux​

You must use the same SELinux mode on the Appcircle server and the Appcircle DMZ server.

You can check the SELinux mode with the command below.

getenforce

DNS Entries​

For Appcircle DMZ server to work successfully, you should configure the DNS records.

For the clients that will connect to the Appcircle DMZ server should resolve 3 domains; Enterprise App Store, Testing Distribution and authentication domains.

These domains should be resolved to the Appcircle DMZ server IP. The domains may vary according to the Appcircle server configuration. To check the current configured domains, you can follow the steps below:

  • Login to the Appcircle server with SSH.

  • Go to the Appcircle server directory.

cd appcircle-server
info

The spacetech in the example codes below are example project name.

Please find your own project name and replace spacetech with your project name.

To see projects, you can check the projects directory.

ls -l ./projects
  • Update the environment variable PATH with the required dependencies.
export PATH=$PATH:$(pwd)/deps/bin
  • Check if your Enterprise App Store custom domain is enabled.
yq '.storeWeb.customDomain.enabled' ./projects/spacetech/export/.global.yaml
  • Check the Enterprise App Store custom domain.
yq '.storeWeb.customDomain.domain' ./projects/spacetech/export/.global.yaml

Output:

store.spacetech.com
  • Check if your Testing Distribution custom domain is enabled.
yq '.testerWeb.customDomain.enabled' ./projects/spacetech/export/.global.yaml
  • Check the Testing Distribution custom domain.
yq '.testerWeb.customDomain.domain' ./projects/spacetech/export/.global.yaml

Output:

dist.spacetech.com
  • Check the authentication domain of the Appcircle server.
yq '.keycloak.external.domain' ./projects/spacetech/export/.global.yaml

Output:

auth.appcircle.spacetech.com
  • Check the API domain of the Appcircle server.
yq '.apiGateway.external.domain' ./projects/spacetech/export/.global.yaml

Output:

api.appcircle.spacetech.com

According to the sample outputs above, the needed domains that clients accessing via the internet should know are as follows:

  • store.spacetech.com: Custom Enterprise App Store domain.
  • dist.spacetech.com: Custom Testing Distribution domain.
  • auth.appcircle.spacetech.com: Appcircle authentication domain.

Also the Appcircle DMZ server should be resolving some of the Appcircle server domains such as authentication and API domains.

These domains should be resolved to the Appcircle server IP. The domains may vary according to the Appcircle server configuration.

According to the sample outputs above, the needed domains that Appcircle DMZ server should know are as follows:

  • api.appcircle.spacetech.com: Appcircle API domain.
  • auth.appcircle.spacetech.com: Appcircle authentication domain.
caution

There is a common domain here. Be aware that the auth subdomain that the clients that will access from the internet and the Appcircle DMZ server will connect to should mean two different things.

tip

You can change the Appcircle authentication domain for the users access from the internet and make it different from the internal domain using a custom domain. See the FAQ below for details.

Creating the Appcircle DMZ Server Configuration​

To create the Appcircle DMZ server configuration, you should login to the Appcircle server.

You will create all the configuration files on the Appcircle server and then move the created configuration files to the Appcircle DMZ server.

To create the Appcircle DMZ server configuration, you can follow the steps below.

caution

If you modify the global.yaml configuration file for the Appcircle server, you must also update the configuration on the Appcircle DMZ server. Otherwise, Appcircle services may exhibit unusual behavior or malfunction.

  • Login to the Appcircle server with SSH.

  • Go to the Appcircle server directory.

cd appcircle-server
  • Stop the running Appcircle server.
info

The spacetech in the example codes below are example project name.

Please find your own project name and replace spacetech with your project name.

To see projects, you can check the projects directory.

ls -l ./projects
./ac-self-hosted.sh -n spacetech down
  • Create the new configuration files for the Appcircle DMZ and the Appcircle server.
./ac-self-hosted.sh -n spacetech export --dmz
info

The --dmz flag in the export subcommand above creates the configuration files according to your global.yaml file of your project for the both the Appcircle DMZ server and the Appcircle server.

  • Check the exported DMZ directory that contains the required files to create Appcircle DMZ server.
ls -lah projects/spacetech/export/dmz/
  • Start the Appcircle server.
./ac-self-hosted.sh -n spacetech up
  • Compress the directory into a tarball in the Appcircle server.
tar -czf dmz.tar.gz -C projects/spacetech/export/dmz/ .
  • Transfer the dmz.tar.gz file to the Appcircle DMZ server with a file transfer protocol like scp or ftp.

Creating the Appcircle DMZ Server​

Create Appcircle DMZ Directory​

You need to create a directory for the Appcircle DMZ server and extract the transferred configuration files.

  • Create a Appcircle DMZ server.
mkdir -p appcircle-server-dmz
  • Extract the tarball you transferred from the Appcircle server.
tar -xzf dmz.tar.gz -C appcircle-server-dmz
  • Change directory into the new directory.
cd appcircle-server-dmz

Configure the System​

Install the required packages and configurations on the system.

caution

You need to have root access on your system for this step. Being able to run sudo is sufficient for the following step. (sudoer)

Run the command without sudo. The script will ask for the user password if it's required.

./ac-self-hosted-dmz.sh -i

Starting the Appcircle DMZ Server​

After you have configured the system with the steps above, you are ready to run the Appcircle DMZ server.

  • Start the Appcircle DMZ server.
./ac-self-hosted-dmz.sh up
  • Check the health of the Appcircle DMZ services.
./ac-self-hosted-dmz.sh check
caution

Be sure that all the services are running and healthy. If there are connection problems between the Appcircle DMZ server and the Appcircle server, the services won't be healthy.

Stopping the Appcircle DMZ Server​

If you need to stop the Appcircle DMZ server in a case, you can run the the command below:

./ac-self-hosted-dmz.sh down

Upgrading Appcircle DMZ and Appcircle server​

If there is a new Appcircle server version available and you want to update, you can follow the steps below to update the Appcircle server and the Appcircle DMZ server.

caution

When upgrading an Appcircle server, it is critical to also update the Appcircle DMZ server. If you don't, Enterprise App Store and Testing Distribution may not function as expected.

caution

Be aware that this process will cause downtime since it requires a restart of the Appcircle server.

  • Login to the Appcircle DMZ server.

  • Go to the Appcircle DMZ server directory.

cd appcircle-server-dmz
  • Stop the Appcircle DMZ Server.
./ac-self-hosted-dmz.sh down
  • Delete the Appcircle DMZ server directory.
cd .. && rm -rf appcircle-server-dmz

Appcircle DMZ Server Monitoring​

By default, the Appcircle DMZ server will try to send the container logs to the Appcircle server.

You can check the container logs on the Appcircle monitoring page. For more details about checking the logs, you can check the Monitoring page.

Restarting the Appcircle DMZ Server Host​

For Docker users, there are built-in mechanisms that handle container restarts, eliminating the need for manual intervention.

However, Podman users will need to create a systemd unit service to ensure the application starts automatically upon server reboot.

With Docker, you can rely on the built-in restart policies to handle the automatic startup of your Appcircle server.

Docker will automatically restart the server services if the host reboots.

This eliminates the need for any additional steps or configurations to ensure your application restarts upon host restart.

Troubleshooting & FAQ​

How can we change the Appcircle authentication domain on the DMZ server for internet users?​

You can use an additional custom domain for Appcircle authentication so that internet users can access authentication services from the internet without using the internal auth subdomain.

caution

The custom domain applies to the Appcircle DMZ server only. When connecting to the Appcircle server located within the private network, you should continue to utilize the default auth sudomain for Appcircle authentication services.

Follow the steps below to make relevant configurations on the Appcircle server.

info

This feature is supported for Appcircle server version 3.22.0 or later.

caution

Be aware that this process will cause downtime since it requires a restart of the Appcircle server.

  • Login to the Appcircle server with SSH.

  • Change directory to Appcircle server.

cd appcircle-server
info

The spacetech in the example codes below are example project name.

Please find your own project name and replace spacetech with your project name.

To see projects, you can check the projects directory.

ls -l ./projects
  • Edit the global.yaml file of your project.
vi ./projects/spacetech/global.yaml
  • Add or update the keycloak.dmzCustomDomain parameter as below.
info

Please keep in mind that the keycloak key might already exist in your global.yaml file. In that case, find the key to add or update the dmzCustomDomain part.

If keycloak does not exist, then you can add it to the global.yaml file of your project.

keycloak:
  dmzCustomDomain:
    enabled: true
    domain: auth-ac.spacetech.com
  • Upgrade the Appcircle server and DMZ server for changes to be applied.

Need help?​

Get help from Appcircle's support team, or see how others are using Appcircle by joining our Slack Channel.

Slack
No description available
join.slack.com
Preview of Slack