ITFlow on AWS User Guide

Overview

ITFlow is an open source IT documentation and business management platform for managed service providers and internal IT teams. It records every client along with their contacts, locations, assets, networks and credentials, and runs the work around them: tickets with email parsing and a client portal, projects, invoices, quotes, recurring billing, expenses, and domain and SSL certificate expiry tracking. An encrypted credential vault with TOTP support keeps client passwords and second factors alongside the documentation that explains them.

This image runs ITFlow behind Apache with libapache2-mod-php on PHP 8.3, with the mysqli, intl, curl, mbstring, gd and xml extensions ITFlow requires. MariaDB provides the database, on the same instance and reachable over a local unix socket only. ITFlow's scheduled jobs (mail queue, ticket email parser, domain and certificate refreshers) run every five minutes through a systemd timer using the PHP command line, never from a public web endpoint.

The image is served over HTTPS. ITFlow refuses to render a sign-in form over plain HTTP, because it stores your clients' passwords and TOTP secrets in an encrypted vault, so port 443 is the only way in and port 80 permanently redirects to it (a /healthz endpoint stays reachable on plain HTTP for load balancer probes).

No administrator password ships in this image. ITFlow derives its credential vault master key from the administrator password, so the account has to be created with its final password rather than rotated afterwards. This image therefore installs ITFlow on the first boot of every deployed instance using ITFlow's own official installer, generating a fresh database password, a fresh administrator password and a fresh self signed TLS certificate unique to that instance. Two instances launched from the same AMI never share secrets. The credentials are written to /root/itflow-credentials.txt with mode 0600 so only the root user can read them.

The MariaDB data directory and your uploaded client documents, ticket attachments and invoice PDFs live on a dedicated EBS volume mounted at /data, separate from the operating system disk, so they can be snapshotted and grown independently. The image is hardened beyond a stock install: the web installation wizard is deleted rather than merely disabled, PHP execution is blocked in the customer writable uploads tree, and the vendored library tree and command line installers are denied from the web.

Prerequisites

Before you deploy this image you need:

• An Amazon Web Services account where you can launch EC2 instances
• IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
• An EC2 key pair in the target Region for SSH access to the instance
• A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network and inbound port 443 (and port 80 for the redirect) from the networks your team will reach ITFlow on
• The AWS CLI (version 2) installed locally if you plan to deploy from the command line

Step 1: Launch the Instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images choose AWS Marketplace AMIs and search for ITFlow. Select the cloudimg listing and choose Select, then Continue on the subscription summary.

Choose an instance type (the listing recommends m5.large), your key pair, and a security group that allows inbound 22 from your management network and 443 (plus 80 for the redirect) from your team. Leave the storage defaults; the image adds its own dedicated data volume. Launch the instance.

Step 2: Launch the Instance from the AWS CLI

You can also launch from the command line. Replace the AMI id with the one from the listing's Usage instructions for your Region, and use your own key pair, security group and subnet ids:

aws ec2 run-instances \
  --image-id ami-0123456789abcdef0 \
  --instance-type m5.large \
  --key-name your-key-pair \
  --security-group-ids sg-0123456789abcdef0 \
  --subnet-id subnet-0123456789abcdef0 \
  --region us-east-1

Step 3: Connect and Retrieve Initial Credentials

Connect over SSH with the key pair you selected and the public IP address from step 1 or 2. The SSH login user depends on the operating system of the AMI variant you launched:

Connect with ssh -i <path-to-key.pem> ubuntu@<instance-public-ip>, substituting your key path and the instance's public IP address.

The per instance administrator and database credentials are written to a root only file on first boot. Read it with:

sudo cat /root/itflow-credentials.txt

The file lists the sign-in URL, the administrator email and password, and the MariaDB database name, user and password. Store the administrator password in your password manager and treat this file as sensitive.

Step 4: Verify the Stack is Running

ITFlow is served by two systemd units. Confirm they are active:

systemctl is-active apache2 mariadb

Each line returns active. Confirm the appliance answers over HTTPS on the loopback health endpoint (the -k flag accepts the self signed certificate):

curl -ks -o /dev/null -w '%{http_code}\n' https://127.0.0.1/healthz

This returns 200. You can confirm the sign-in form renders over TLS, and that plain HTTP redirects to HTTPS:

curl -ks -o /dev/null -w 'login over https: %{http_code}\n' https://127.0.0.1/login.php
curl -s  -o /dev/null -w 'http redirect: %{http_code}\n' http://127.0.0.1/login.php

The scheduled jobs (mail queue, ticket email parser, domain and certificate refreshers) run every five minutes through a systemd timer, enabled on the image:

systemctl is-enabled itflow-scheduler.timer

Step 5: Inspect the Per Instance TLS Certificate

The image ships no usable certificate; first boot generates a self signed certificate for this instance's own address. Inspect it:

sudo openssl x509 -in /etc/ssl/cloudimg/itflow.crt -noout -subject -dates

The subject shows your instance's address as the common name. Because the certificate is self signed, your browser will warn you the first time you visit; that is expected until you install a trusted certificate (step 8).

Step 6: First Login

Browse to https://<instance-public-ip>/ and accept the browser's certificate warning. Sign in with the administrator email and password from /root/itflow-credentials.txt. You land on the ITFlow dashboard.

The first thing to do is change the administrator password from the top right user menu under My Preferences, and add your own details. Then work through the Admin area to set your company details, localization, mail and ticket settings.

Step 7: Set Your Real Hostname (Important Before Inviting Clients)

ITFlow builds the links it emails (ticket portal, invoices, quotes, guest shares, new user password setup) from $config_base_url in /var/www/itflow/config.php, which first boot set to the address it could detect. Before you invite clients, set it to the public DNS name your clients will use, so those emailed links resolve. Substitute your real hostname:

sudo sed -i "s|^\$config_base_url = .*|\$config_base_url = '<your-domain>';|" /var/www/itflow/config.php

Every ITFlow install has to make this choice; it is not specific to this image.

Step 8: Install a Trusted Certificate with Let's Encrypt

Once your instance has a public DNS name pointing at it, replace the self signed certificate with a trusted one. Install certbot and obtain a certificate for your hostname, then point Apache's SSLCertificateFile and SSLCertificateKeyFile in /etc/apache2/sites-available/cloudimg-itflow.conf at the issued files and reload Apache:

sudo apt-get install -y certbot
sudo certbot certonly --standalone -d itflow.your-domain.com --agree-tos -m admin@your-domain.com --non-interactive

You can also use your own certificate authority; drop the certificate and key onto the instance and update the same two Apache directives.

Step 9: Core Workflows

ITFlow organises everything around clients. From the sidebar:

• Clients — add a client, then record its contacts, locations, assets, networks, racks, documents and credentials. The credential vault encrypts client passwords and TOTP secrets, and the vault key is derived from your administrator password.
• Tickets — open, assign and reply to tickets; configure inbound email parsing under Admin → Mail so client emails become tickets, and enable the client portal for self service.
• Projects — plan and track project work against a client.
• Invoices, Quotes and Recurring — bill for work, send quotes, and set up recurring billing; connect a payment provider under Admin → Payment Providers.
• Domains and Certificates — track domain and SSL certificate expiry; the scheduled jobs refresh these automatically.

Step 10: Backups

Your data is the MariaDB database and the uploads tree on /data. Back both up regularly. Dump the database (the credentials are in /root/itflow-credentials.txt) and archive the uploads:

sudo mariadb-dump itflow > /backup/itflow-$(date +%F).sql
sudo tar czf /backup/itflow-uploads-$(date +%F).tar.gz -C /var/www/itflow uploads

Copy the backups off the instance (for example to Amazon S3) and consider EBS snapshots of the /data volume.

Step 11: Storage Layout

The database and uploads live on a dedicated EBS volume mounted at /data, separate from the operating system disk:

df -h /data
findmnt /var/lib/mysql
findmnt /var/www/itflow/uploads

/var/lib/mysql (the MariaDB data directory) and /var/www/itflow/uploads (client documents and attachments) are bind mounted onto /data, so both tiers sit on the resizable data volume rather than the root disk.

Screenshots

The ITFlow sign-in page, served over HTTPS on first boot with a per instance administrator credential:

The ITFlow dashboard after signing in, with the full sidebar of clients, support, billing and finance modules:

The clients list — the heart of ITFlow, with each client's billing summary and quick actions:

The administration area — company details, users and roles, tags and categories, taxes, payment providers, ticket statuses and templates:

Support

This image is backed by 24/7 technical support from cloudimg, covering ITFlow deployment, TLS certificate installation including Let's Encrypt and your own certificate authority, mail and ticket email parsing, client portal configuration, credential vault and TOTP usage, invoicing, quoting and recurring billing, domain and SSL certificate expiry tracking, upgrades, backup and restore, and MariaDB administration. Contact support through the channel listed on the AWS Marketplace listing.