Skip to main content
Version: V1-Next

Platform Installation Guide

This guide covers the unified installation process for CIVITAS/CORE platform using the cc_cli tool. This process is the same for both local and remote deployments after cluster setup is complete.

Overview​

The platform installation process uses a consistent workflow regardless of your deployment type:

  1. Prerequisites Check - Verify cluster and tools are ready
  2. Configuration - Use cc_cli wizard to create inventory
  3. Validation - Run cc_cli validate to check configuration
  4. Installation - Execute cc_cli exec to deploy platform

Prerequisites​

Cluster Requirements​

Before starting platform installation, ensure you have a running Kubernetes cluster:

For Remote/Cloud Deployments:

For Local Deployments:

Control System Requirements​

Your control system (the machine from which you run the installation) needs:

Required Software:

  • Python 3.8 or higher
  • kubectl (configured and working)
  • helm
  • curl
  • git

Verify Prerequisites:

# Check Python version
python3 --version

# Verify kubectl access
kubectl cluster-info

# Check helm
helm version

# Test cluster access
kubectl get nodes

Installation Process​

Step 1: Prepare Repository​

Clone the CIVITAS/CORE repository:

git clone https://gitlab.com/civitas-connect/civitas-core/civitas-core.git
cd civitas-core

Note: If you need customizations or want to configure add-ons, fork the repository first and clone your fork.

Step 2: Install CC CLI Tool​

Install the CIVITAS/CORE CLI tool:

pip install --extra-index-url https://gitlab.com/api/v4/projects/62227605/packages/pypi/simple cc-cli

Verify successful installation of cc_cli:

cc_cli --help

Step 3: Configure Platform​

Use the cc_cli wizard to create your inventory configuration:

cc_cli wizard

The wizard will guide you through all necessary configuration options.

After completing the wizard, your inventory will be saved as cc_cli_inventory.yml.

warning

cc_cli_inventory.yml is in .gitignore by default because it usually contains sensitive data like passwords. Take adequate measures to protect the sensitive information inside this file!

The generated inventory is supposed to be working out of the box. If needed you can make manual adjustments now. For detailed guidance on the configuration process, deployment-specific settings, and advanced options, see the Inventory Configuration Guide.

Step 4: Validate Configuration​

Validate your inventory configuration:

cc_cli validate

This command will check your cc_cli against a schema wich can be found in ./core_platform/inventory_schema.json

Fix any validation errors before proceeding to installation.

Step 5: Install Platform​

Execute the platform installation:

cc_cli exec

This command will:

  • Deploy Components - Install all enabled platform components
  • Configure Networking - Set up ingresses and services
  • Create Certificates - Generate/request SSL certificates (if required)
  • Initialize Databases - Set up database schemas and users
  • Configure Authentication - Initialize Keycloak and user accounts
  • Apply Configurations - Set up component integrations

Step 6: Post-Installation Verification​

After installation completes, verify the platform:

Check Pod Status:

# List all platform pods
kubectl get pods --all-namespaces

# Check for any failed pods
kubectl get pods --all-namespaces --field-selector=status.phase!=Running

Test Web Access:

# For local deployments
curl -k https://civitas.test

# For remote deployments
curl https://your-domain.com

Access Platform Services:

Local Deployments:

Remote Deployments:

Advanced Configuration​

Updating Configuration​

You can modify your configuration and re-run the wizard:

# Re-run wizard with existing configuration
cc_cli wizard

# Validate and apply changes
cc_cli validate
cc_cli exec

Note: Some configuration values cannot be changed after initial installation to prevent data loss.

Partial Updates​

Install or update specific components using tags:

# Update only Keycloak
cc_cli exec --tags acc_keycloak

Custom Inventory​

For advanced users, you can manually edit the generated inventory:

# Edit the inventory file
vim cc_cli_inventory.yml

# Validate custom changes
cc_cli validate

# Apply changes
cc_cli exec

Troubleshooting​

Common Installation Issues​

As a general recommendation, we suggest to use k9s for inspection and administration of you cluster.

Validation Failures

  • Check kubectl connectivity: kubectl cluster-info
  • Verify cluster resources: kubectl get nodes
  • Review error messages for specific validation failures

Pod Startup Failures

# Check pod status
kubectl get pods --all-namespaces

# Investigate failed pods
kubectl describe pod <pod-name> -n <namespace>
kubectl logs <pod-name> -n <namespace>

Certificate Issues (Local)

  • Browser warnings are expected with self-signed certificates
  • Add certificate exceptions or install CA certificate
  • Certificate location: ./local_deployment/.ssl/civitas.crt

Certificate Issues (Remote)

  • Verify domain points to cluster IP
  • Check Let's Encrypt rate limits
  • Review cert-manager logs: kubectl logs -n cert-manager deployment/cert-manager

Storage Issues

# Check storage classes
kubectl get storageclass

# Review PVC status
kubectl get pvc --all-namespaces

# Check for storage provisioning issues
kubectl describe pvc <pvc-name> -n <namespace>

Network/Ingress Issues

# Check ingress controller
kubectl get pods -n ingress-nginx

# Review ingress configurations
kubectl get ingress --all-namespaces

# Test internal connectivity
kubectl run test-pod --image=busybox -it --rm -- sh

Getting Help​

Check Installation Logs: cc_cli will create very verbose logfiles in the logsfolder for each run. In case you encounter issues while running the playbook, it's always a good idea to check the logs-folder.


**Resource Monitoring:**
```bash
# Check resource usage
kubectl top nodes
kubectl top pods --all-namespaces

# Monitor cluster events
kubectl get events --all-namespaces --sort-by='.lastTimestamp'

Next Steps​

After successful platform installation:

  1. Configure Users and Access - Set up user accounts and permissions
  2. Customize Components - See Advanced Customization section in Inventory Configuration Guide
  3. Set Up Monitoring - Configure alerts and dashboards
  4. Import Data - Load initial datasets and configurations
  5. Test Integration - Verify all components work together
  6. Backup Configuration - Save your inventory and certificates

For ongoing platform management, see: