Backend Installation Guide

Last updated: July 31, 2026Latest Frontend Version: 2.17.4

TL;DR

Ansible-based installer. Requires network, DNS, and TLS preparation first
Single command to run: ./ticrypt-setup.sh
Complete the Pre-Installation Checklist before starting

Pre-Installation Checklist

Complete every item below before running the installer. A misconfigured network, missing DNS record, or invalid TLS certificate will cause installation to fail or produce a non-functional system.

🗄️Hardware - Minimum Requirements

Single server with 32+ CPU cores (virtualization extensions enabled in BIOS)

128 GB+ RAM

2 TB+ disk space

A distributed file system accessible to all servers (required for VM images, drives, and shared storage)

These are minimum specifications for a combined backend + VM host node (demo or small production). Production deployments require more. See the Infrastructure Guide for architecture-specific sizing.

🐧Operating System

RHEL 8/9 or Rocky Linux 8/9 (or compatible RPM-based distribution)

Access to RPM package repositories (internet or local mirror)

Python 3 installed on all target nodes

Ansible installed on the control node

🌐Network

tiCrypt uses an OpenVSwitch-based network architecture with three isolated VLAN-backed virtual networks (secure, service, and data-in). The trunk switch carries all three VLANs over a bonded interface (bond0); VLAN 1081 backs br-secure for VM-to-VM traffic, VLAN 1082 backs br-service for VM-to-backend traffic (serving HTTPS on port 443 and connection tunnels on ports 6000-6100), and VLAN 1083 backs br-datain for SFTP ingress on port 2022. Coordinate the following with your network team before installation.

VLANs

Three VLAN IDs reserved for tiCrypt private networks (e.g., 1081 secure, 1082 service, 1083 data-in). These VLANs must not be forwarded outside the switches connecting the tiCrypt nodes.

Physical switch ports connecting the backend and all VM hosts configured as trunk ports carrying the assigned VLANs

A bonded or dedicated physical interface (e.g., bond0) available on the backend and every VM host for VLAN traffic

Three private, non-overlapping IP ranges assigned (one per network, must not overlap with the host or backend management networks)

Ports

Port 443 open on all tiCrypt servers (TLS/HTTPS)

Ports 6000-6100 open on ticrypt.* (VM connection tunnels)

Port 2022 open on the SFTP server (SFTP data ingress)

Port 22 open for management access (SSH)

If you are not using an external firewall, the tiCrypt installation scripts configure an internal firewall (NFTables) that blocks all other inbound traffic.

📡DNS

A record for ticrypt.example.com (main backend and web interface)

A record for audit.example.com (tiCrypt Audit interface)

A record for sftp.example.com (SFTP data ingress)

A record for mailbox.example.com (URL-based data ingress)

All four records must point to the server IP. Replace example.com with your domain.

🔒TLS Certificates

TLS certificate obtained covering all four subdomains (SAN or wildcard)

Certificate and private key files present on the server

Production note: For production deployments, consider issuing a separate certificate for the main backend (ticrypt.example.com) rather than sharing one wildcard or SAN certificate across all four subdomains. The sftp and mailbox services are exposed to external parties, making their certificates a higher compromise risk. Isolating the core backend onto its own certificate ensures that a compromised ingress certificate cannot be used to impersonate it.

Install

Supported Installation Method

ticrypt-setup is the only supported installation method.

Download the setup archive, extract it, edit the configuration files, and run the installer:

wget https://storage.googleapis.com/ticrypt/install/ticrypt-setup-{versions.setup}.tgz
tar -xzf ticrypt-setup-{versions.setup}.tgz
cd ticrypt-setup
# edit inventory.ini and ticrypt.yml before running (see Configuration below)
./ticrypt-setup.sh

The extracted directory contains the Ansible playbooks, configuration templates, and the installation script ticrypt-setup.sh. The installer:

Validates the Ansible environment
Loads your configuration
Installs required system dependencies
Deploys and configures all 10 backend services
Applies configuration templates
Enables all services automatically

Configuration

The installer uses two primary configuration files: inventory.ini and ticrypt.yml. Edit both files inside the ticrypt-setup directory before running ticrypt-setup.sh.

inventory.ini - Node inventory

# -----------------------------------------------------------------------------
# tiCrypt Ansible Inventory
#
# - Define backend nodes in [backend]
# - Define worker nodes in [workers]
# - Provide common SSH settings in [all:vars]
#
# Notes:
# - Use hostnames if DNS is in place; otherwise set ansible_host=<ip>
# - The ansible_user must be able to sudo without being prompted for a password
# - Ensure Python 3 exists on each target node and set ansible_python_interpreter
# -----------------------------------------------------------------------------

[backend]
# Primary backend node (API/services, database, etc., depending on your playbooks)
backend01 ansible_host=10.0.0.10

[workers]
# Worker nodes used for compute / job execution / services as defined by your roles
worker01 ansible_host=10.0.0.20
worker02 ansible_host=10.0.0.21

[all:vars]
# SSH user used by Ansible to connect to all nodes above
ansible_user=ticrypt

# Path to Python on the target nodes (required for Ansible modules)
ansible_python_interpreter=/usr/bin/python3

# Optional: if your environment requires privilege escalation
# ansible_become=true
# ansible_become_method=sudo

# Optional: if you use SSH keys in a non-default location
# ansible_ssh_private_key_file=~/.ssh/id_rsa

# Optional: if your SSH daemon uses a non-standard port
# ansible_port=22

ticrypt.yml - Deployment configuration

# -----------------------------------------------------------------------------
# tiCrypt Deployment Configuration
#
# This file provides deployment-specific values consumed by Ansible templates
# and roles during installation. Update values to match your environment.
#
# Guidance:
# - Use fully qualified hostnames where appropriate
# - Ensure all paths are valid and writable by the installed services
# - If you change this file after installation, re-run ticrypt-setup.sh
# -----------------------------------------------------------------------------

# A short identifier used in logs, tags, and generated artifacts
deployment_name: ticrypt-prod

# -----------------------------------------------------------------------------
# Backend service configuration
# -----------------------------------------------------------------------------
backend:
  # Address the backend binds to. 0.0.0.0 listens on all interfaces.
  listen_address: 0.0.0.0

  # Public/service port for the backend API (adjust to match your environment)
  listen_port: 8443

  # Optional: external hostname clients use to reach the backend
  # public_hostname: ticrypt.example.edu

  # Optional: if TLS termination is handled elsewhere, document that here
  # tls_terminated_upstream: false

# -----------------------------------------------------------------------------
# Database configuration (MongoDB)
# -----------------------------------------------------------------------------
database:
  # Database host. Use localhost if MongoDB is colocated with the backend.
  host: localhost

  # Database port
  port: 27017

  # Database name
  name: ticrypt

  # Optional: credentials if required by your deployment
  # username: ticrypt
  # password: change-me

  # Optional: replica set or connection options
  # options: "replicaSet=rs0&authSource=admin"

# -----------------------------------------------------------------------------
# Storage paths
# -----------------------------------------------------------------------------
storage:
  # Root directory for persistent tiCrypt data (keys, metadata, etc.)
  data_root: /var/lib/ticrypt

  # Temporary working directory for installers, staging, and intermediate files
  temp_root: /var/lib/ticrypt/tmp

  # Optional: additional mounts/paths used in your deployment
  # inbox_root: /var/lib/ticrypt/inboxes
  # drives_root: /var/lib/ticrypt/drives

# -----------------------------------------------------------------------------
# Logging configuration
# -----------------------------------------------------------------------------
logging:
  # Log level (common values: DEBUG, INFO, WARNING, ERROR)
  level: INFO

  # Directory where logs are written
  log_dir: /var/log/ticrypt

  # Optional: log rotation behavior if your roles support it
  # rotate: true
  # max_size_mb: 100
  # max_files: 10

# -----------------------------------------------------------------------------
# Optional: integrations / feature flags (uncomment if your roles support these)
# -----------------------------------------------------------------------------
# integrations:
#   slurm:
#     enabled: false
#     # controller_host: slurmctld.example.edu
#     # rest_api_url: https://slurmrest.example.edu
#
# security:
#   # Whether to enforce hardened defaults (depends on role support)
#   hardened_defaults: true
#
# networking:
#   # If your environment requires explicit interface binding
#   # interface: eth0

Post-Installation Checklist

✅Verify Installation

All 10 backend services are running (

systemctl status ticrypt-auth ticrypt-rest ticrypt-file-manager ticrypt-storage ticrypt-vm ticrypt-proxy ticrypt-logger ticrypt-stats ticrypt-notifications ticrypt-maintenance

)

No startup errors in /var/log/ticrypt

Nginx configured with valid TLS certificates. See Nginx TLS Configuration for certificate verification, Diffie-Hellman parameter generation, and SELinux configuration.

Worker nodes registered and reachable from the backend

Connectivity validated using the tiCrypt frontend or the REST API

⚙️Service Configuration

Review Auth Service (ticrypt-auth) for authentication, MFA, key escrow, and split credential settings

Review VM Service (ticrypt-vm) for Libvirt realm, hardware profile, and cost function configuration

Adjust other service configurations as needed. See Service Configuration for all options.Optional

Pre-Installation Checklist​

Install​

Configuration​

Post-Installation Checklist​

Pre-Installation Checklist

Install

Configuration

Post-Installation Checklist