Module Structure¶

This page documents the structure and conventions for TAPPaaS modules.

Module Definition¶

Each TAPPaaS module is defined by a <module>.json file that specifies its configuration, resource requirements, and dependencies.

Core Fields¶

Basic module metadata and dependency declarations used by all modules.

Cluster:VM Service Configuration¶

Fields used by the cluster:vm service to create and configure the module's virtual machine.

Cluster:HA Service Configuration¶

Fields used by the cluster:ha service to configure high availability and replication.

Firewall:proxy Service Configuration¶

Fields used by the firewall:proxy service to configure reverse proxy routing via Caddy on OPNsense.

Standard Scripts¶

TAPPaaS provides standard scripts for module lifecycle management. These scripts are located in /home/tappaas/bin/ on the tappaas-cicd module.

Install¶

The install-module.sh script installs a module and its dependencies.

Usage:

install-module.sh <module-name> [--<field> <value>...]
install-module.sh vaultwarden
install-module.sh litellm --node tappaas2

Parameters:

Scripts Sourced:

• copy-update-json.sh - Copies and validates module JSON configuration
• common-install-routines.sh - Shared installation routines

Execution Flow:

flowchart TB
    A[install-module.sh] --> B[1. Copy and validate module JSON]
    B --> C[2. Validate dependencies exist]
    C --> D[3. Validate service scripts exist]
    D --> E[4. Execute dependency install-service.sh]
    E --> F[5. Execute module install.sh]

1. Copy and validate - Copies <module>.json to config directory, applies field overrides
2. Validate dependencies - Checks each service in dependsOn exists and is provided by another module
3. Validate service scripts - Ensures the module has scripts for each service it provides
4. Execute dependency installers - Calls install-service.sh for each dependency's provider
5. Run module installer - Executes the module's own install.sh if present

Module install.sh:

Each module may provide an install.sh script in its directory. This script receives the module name as its first argument and should handle module-specific installation tasks.

Update¶

The update-module.sh script updates a module and its dependencies.

Usage:

update-module.sh <module-name>
update-module.sh vaultwarden

Parameters:

Scripts Sourced:

• common-install-routines.sh - Provides check_json() function

Execution Flow:

flowchart TB
    A[update-module.sh] --> B[1. Validate module JSON config]
    B --> C[2. Verify dependencies available]
    C --> D[3. Execute module pre-update.sh]
    D --> E[4. Execute dependency update-service.sh]
    E --> F[5. Execute module update.sh]

1. Configuration validation - Verifies the module's JSON config is well-formed
2. Dependency verification - Confirms each declared dependency exists and is available
3. Pre-update hook - Executes the module's optional pre-update.sh script
4. Service dependencies - Runs each dependency provider's update-service.sh
5. Module update - Executes the module's own update.sh script

Module Scripts:

Delete¶

The delete-module.sh script removes a module and cleans up its dependencies.

Usage:

delete-module.sh <module-name>
delete-module.sh vaultwarden

Parameters:

Scripts Sourced:

• common-install-routines.sh - Provides check_json() function

Execution Flow:

flowchart TB
    A[delete-module.sh] --> B[1. Validate module JSON config]
    B --> C[2. Execute module delete.sh]
    C --> D[3. Execute dependency delete-service.sh in reverse order]
    D --> E[4. Remove module configuration]

1. Configuration validation - Verifies the module's JSON config exists
2. Module delete - Executes the module's own delete.sh script first
3. Service cleanup - Runs each dependency provider's delete-service.sh in reverse order of dependsOn
4. Config removal - Removes the module's JSON configuration file

Key Differences from Install/Update:

Module Scripts:

Test¶

To be documented.

Service Scripts¶

Service scripts are provided by modules to handle the services they offer (declared in the provides field). These scripts are located in <module>/services/<service-name>/ and are called by the standard install and update scripts when other modules depend on them.

Directory Structure¶

<module>/
├── <module>.json
├── install.sh
├── update.sh
└── services/
    └── <service-name>/
        ├── install-service.sh
        └── update-service.sh

install-service.sh¶

Called by install-module.sh when a module depends on this service.

Parameters:

Responsibilities:

• Read the dependent module's configuration from /home/tappaas/config/<module-name>.json
• Provision resources required by the dependent module
• Configure the service to support the new dependent

Example: cluster/services/vm/install-service.sh

This script creates a VM for a dependent module:

flowchart TB
    A[install-service.sh] --> B[Validate module JSON exists]
    B --> C[Extract VM settings from config]
    C --> D[Get target node]
    D --> E[scp config to target node]
    E --> F[ssh: Create-TAPPaaS-VM.sh]
    F --> G[Confirm VM creation]

Scripts/Commands Used:

update-service.sh¶

Called by update-module.sh when updating a module's dependencies.

Parameters:

Responsibilities:

• Read current configuration for the dependent module
• Apply any configuration changes
• Update service state as needed

Example: cluster/services/ha/update-service.sh

This script manages High Availability configuration:

Configuration Values Used:

Proxmox Commands Used:

Example: templates/services/nixos/update-service.sh

This script updates the OS on NixOS-based VMs:

flowchart TB
    A[update-service.sh] --> B[Get vmname, vmid, node from config]
    B --> C[Call update-os.sh]
    C --> D[update-os.sh auto-detects OS type]
    D --> E[Execute NixOS or Debian update]

Writing Service Scripts¶

When creating a new service:

1. Create the directory <module>/services/<service-name>/
2. Add install-service.sh for initial provisioning
3. Add update-service.sh for ongoing updates
4. Source common-install-routines.sh for helper functions
5. Use get_config_value to read module configuration with defaults
6. Use set -euo pipefail for strict error handling