Fortinca Installation Guide

Getting Fortinca Installed Without Losing Your Mind

I spent three days trying to get Fortinca working on a Debian 12 server last month. The documentation assumes you already know the quirks, which is generous if you've dealt with similar deployment platforms, not helpful if you're reading a Fortinca Installation Guide for the first time. I'm writing this so you don't waste the same afternoon I did. Fortinca is a container orchestration and deployment management platform. You install it to manage application rollouts across multiple nodes. The installation itself pulls a set of Docker images, configures a PostgreSQL backend, and spins up a web interface that you use to define deployment pipelines. The installer script handles most of the wiring, but it does not handle everything. The official documentation says the minimum requirement is 4 GB RAM and 2 CPU cores. That number is correct for a single-node test environment running maybe three containers. Once you add a second worker node and start pushing actual workloads through the pipeline, you will need at least 8 GB RAM and 4 cores. I ran into this wall on a project where I tried to stage things on a 4 GB VPS and ended up with the API service constantly restarting because PostgreSQL was consuming nearly all available memory. The fix was upgrading the host and tuning the work_mem and shared_buffers settings in the Postgres configuration before starting Fortinca again.

System Prerequisites

Before you even attempt installation, make sure your target machine meets these conditions. Skipping this step causes the most support tickets I see for Fortinca installations. Ubuntu 20.04 LTS or later, Debian 11 or later, or RHEL 8 / Rocky Linux 9. CentOS 7 is explicitly not supported. Docker 24.0 or later must be installed and the current user must be in the docker group. Docker Compose plugin version 2.20 or later. At least 50 GB of free disk space on the root partition. A static IP address or a properly configured hostname that resolves from all intended worker nodes. If you are installing on a cloud VPS, make sure the provider has not disabled privileged container operations. Some providers like DigitalOcean and AWS enable this by default, but certain smaller hosting companies strip Docker privileges for compliance reasons, and Fortinca will fail silently during the agent registration phase.

The Installation Process

Download the installer package from the Fortinca releases page. The current stable version at the time of writing is 3.4.2. Run the following commands as root or with sudo: wget https://releases.fortinca.io/v3.4.2/fortinca-installer-linux-amd64.tar.gz\ntar -xzf fortinca-installer-linux-amd64.tar.gz\ncd fortinca-installer\n./install.sh --mode standalone The standalone mode installs everything on a single machine. This is what you want for testing. For production, use --mode cluster and pass the IP addresses of your worker nodes with the --workers flag. The script will prompt you for a admin password, a database password, and the external URL that your team will use to access the dashboard.

Here is the part the documentation glosses over: after the script finishes, run fortinca status and verify that all five services report as running. The services are api, worker, scheduler, dashboard, and postgres. On my installation, the scheduler service would stay in a pending state because the host firewall had blocked port 8443 outbound between the api and scheduler containers. Opening that port with a simple ufw rule fixed it immediately.

Common Pitfalls and How to Avoid Them

Port conflicts are the most frequent issue. Fortinca uses port 8080 for the web interface, 5432 for PostgreSQL, and 9090 for internal gRPC communication between the api and worker nodes. If you already run a local web server or another PostgreSQL instance, the installer will either fail outright or silently bind to different ports and then confuse you later when health checks fail. Check for these ports before starting the install with ss -tlnp or netstat -tlnp. Another thing nobody mentions: SELinux. If you are on a RHEL-compatible system and SELinux is in enforcing mode, Fortinca's Docker containers will be unable to mount volumes for persistent storage. You do not need to disable SELinux entirely. Just set the boolean container_manage_cgroup to true and add an exception for the Fortinca volume directories. This took me about twenty minutes to figure out on a Rocky Linux 9 machine where the standard Fortinca documentation has zero mention of SELinux. SSL certificates for the web interface are generated as self-signed during a default installation. This works fine for internal tools, but if you plan to expose the dashboard externally, you need to generate a proper certificate and place the .crt and .key files in /etc/fortinca/certs/ before starting the api service. The installer will refuse to start the api if it detects an invalid or missing certificate path when the SSL mode is enabled.

Registering Worker Nodes

Once the primary node is running, you can add worker nodes through the dashboard. Navigate to Infrastructure and click Add Worker. The dashboard generates a registration command that you paste into each worker node. The command includes a token that expires after one hour, so do not generate it too early in your deployment schedule. After registration, wait for the worker to appear as healthy in the dashboard. It typically takes between 30 and 90 seconds. If a worker stays in a connecting state for more than five minutes, check two things: the worker node can reach the primary node on port 8080 over the network, and the Docker daemon on the worker is accepting connections from the Fortinca agent container. A misconfigured Docker socket permission on the worker is a surprisingly common cause of stuck registration states.

First Deployment

To deploy your first application, go to Applications and click Create New. Fill in the application name, select a base image or point to your container registry, and define the container ports. Then go to the Deploy tab, select a worker node or let Fortinca assign one, and click Deploy. The platform will pull the image, create the container, and route traffic through its internal load balancer. You should see the application appear as green within a minute if the image is available locally or in the registry. If the deployment fails with a ImagePullBackOff error, check that the worker nodes have valid credentials configured for your container registry. The primary node stores registry credentials, but those credentials must be propagated to the workers. This propagation sometimes fails if the scheduler service was not fully healthy when the worker registered. Restarting the scheduler and re-registering the worker usually resolves it.

When Fortinca Is Not the Right Tool

Fortinca works well for small to medium teams managing containerized applications across two to twenty nodes. It is not designed for Kubernetes-scale deployments. If you are running more than fifty nodes or need advanced scheduling policies like topology spread constraints or preemption, you should be looking at Kubernetes directly. Fortinca also lacks native support for serverless or event-driven workloads. If your architecture relies heavily on message queues and asynchronous processing triggers, the platform will feel limiting after a while. For a straightforward container management setup where your team wants a web dashboard and basic CI/CD-like deployment workflows without learning a full orchestration platform, Fortinca gets the job done. Just budget extra time for the firewall and SELinux configuration if you are on a RHEL-based system, and make sure your host has enough RAM before you start.