Skip to main content

Backend Installation Guide

Last updated: May 31, 2026Latest Frontend Version: 2.16.20

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 specs for a combined backend + VM host node (demo or small production). Production deployments will 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 following must be coordinated 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 will 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 cert 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 cert cannot be used to impersonate it.

Supported Installation Method

ticrypt-setup with Ansible is the only supported and recommended installation method for tiCrypt backends. All other installation approaches are deprecated and unsupported.

Quick Start​

The following steps install the tiCrypt backend using the supported Ansible-based automation workflow. Review and update the required configuration files as described in the Configuration section before running ticrypt-setup.sh.

wget https://storage.googleapis.com/ticrypt/install/ticrypt-setup-0.1.9.tgz
tar -xzf ticrypt-setup-0.1.9.tgz
cd ticrypt-setup
# edit inventory.ini and ticrypt.yml before running
./ticrypt-setup.sh

Download and Extract​

Download the setup archive:

wget https://storage.googleapis.com/ticrypt/install/ticrypt-setup-0.1.9.tgz

Extract the archive and enter the directory:

tar -xzf ticrypt-setup-0.1.9.tgz
cd ticrypt-setup

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

Configuration​

The installer uses two primary configuration files: inventory.ini and ticrypt.yml.

inventory.ini - Node inventory

The inventory.ini file defines the backend and worker nodes targeted by Ansible.

[backend]
backend01 ansible_host=10.0.0.10

[workers]
worker01 ansible_host=10.0.0.20
worker02 ansible_host=10.0.0.21

[all:vars]
ansible_user=ticrypt
ansible_python_interpreter=/usr/bin/python3

Guidance:

  • Hostnames must be resolvable or mapped using ansible_host
  • The SSH user must have passwordless sudo privileges
  • All nodes must be reachable from the control node
ticrypt.yml - Deployment configuration

The ticrypt.yml file defines tiCrypt-specific configuration values used during installation.

deployment_name: ticrypt-prod

backend:
  listen_address: 0.0.0.0
  listen_port: 8443

database:
  host: localhost
  port: 27017
  name: ticrypt

storage:
  data_root: /var/lib/ticrypt
  temp_root: /var/lib/ticrypt/tmp

logging:
  level: INFO
  log_dir: /var/log/ticrypt

Guidance:

  • Paths must exist or be creatable by the installer
  • Values are consumed directly by Ansible templates
  • Changes require re-running ticrypt-setup.sh to take effect

Running the Installer​

From the root of the extracted ticrypt-setup directory, run:

./ticrypt-setup.sh

The installer will:

  1. Validate the Ansible environment
  2. Load configuration from inventory.ini and ticrypt.yml
  3. Install required system dependencies
  4. Deploy and configure all 10 backend services
  5. Apply configuration templates
  6. Enable and start tiCrypt services

Post-Installation​

Verify Services​

After installation completes, confirm that all backend services are running:

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

Review logs under /var/log/ticrypt for any startup errors.

TLS Certificates​

Nginx must be configured with valid TLS certificates for the tiCrypt backend to serve HTTPS traffic. See Nginx TLS Configuration for the required steps, including certificate verification, Diffie-Hellman parameter generation, and SELinux configuration.

Service Configuration​

Each of the 10 backend services has its own configuration file. After installation, you may need to adjust service-specific settings. The two most complex services to configure are:

  • ticrypt-auth - handles authentication, MFA, key escrow, and split credentials. See Auth Service (ticrypt-auth).
  • ticrypt-vm - manages Libvirt realms, hardware profiles, and cost functions. See Libvirt Realms.

For all other services, see Service Configuration.

Connectivity Check​

  • Verify worker nodes are registered and reachable from the backend
  • Validate connectivity using the tiCrypt frontend or the REST API

Reference Configuration Files (Complete Examples)​

These reference files are provided as complete, copy-paste-ready examples. Update values to match your environment before running ticrypt-setup.sh.

inventory.ini (complete reference)
# -----------------------------------------------------------------------------
# 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 (complete reference)
# -----------------------------------------------------------------------------
# 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