Skip to main content
Enterprise Only

This section is only relevant to Enterprise customers who acquired an on-prem license.

Installation Guide

Detailed installation options for deploying Permit Platform in your environment.

Prerequisites required: Make sure you've completed the prerequisites setup before starting.

Installation Methods​

The simplest method - the installer will guide you through all options:

sudo ./install.sh

The installer will prompt for:

  • Deployment size (Small/Medium/Large)
  • Git repository URL for policies
  • SSH key path for Git access
  • Domain configuration (custom domain or IP access)
  • Multi-server setup (if applicable)

Automated Installation​

For scripted deployments or when you know your configuration:

# Single server with custom domain
sudo ./install.sh \
  --size medium \
  --domain "permit.yourcompany.com" \
  --git-repo "git@github.com:yourorg/permit-policies.git" \
  --git-key "./permit-policy-key"

# Single server with IP access (simpler)
sudo ./install.sh \
  --size medium \
  --ip-access \
  --git-repo "git@github.com:yourorg/permit-policies.git" \
  --git-key "./permit-policy-key"

Configuration File Method​

For complex configurations or repeatable deployments:

# Create configuration file
cat > permit-config.yaml << EOF
deployment:
  mode: single
  size: medium
  
git:
  repository: "git@github.com:yourorg/permit-policies.git"
  private_key_path: "./permit-policy-key"
  
networking:
  domain: "permit.yourcompany.com"
  ssl_enabled: true
  
resources:
  backend_replicas: 3
  celery_replicas: 2
EOF

# Install with configuration
sudo ./install.sh --config permit-config.yaml

Multi-Server High Availability​

For production environments requiring high availability:

Architecture Overview​

Step 1: Initialize Cluster​

Run on the first server:

sudo ./install.sh \
  --mode cluster \
  --size large \
  --domain "permit.yourcompany.com" \
  --git-repo "git@github.com:yourorg/permit-policies.git" \
  --git-key "./permit-policy-key"

Important: Note the join token and server IP displayed at the end of installation.

Step 2: Join Additional Servers​

Run on each additional server:

# Use token and IP from step 1
sudo ./install.sh \
  --mode join \
  --server <server-1-ip> \
  --token <join-token-from-step-1>
  • 3 servers: Minimum for production failover
  • 5 servers: Enterprise-grade maximum availability
  • Odd numbers: Always use odd number of servers for proper clustering

Installation Process​

What Happens During Installation​

  1. System validation (2-3 minutes)

    • Check server requirements
    • Validate Git access
    • Verify permissions

  2. Infrastructure setup (3-5 minutes)

    • Install and configure k3s
    • Set up container registry
    • Configure networking

  3. Platform deployment (2-4 minutes)

    • Deploy all Permit services
    • Configure Git integration
    • Generate security certificates

  4. Final configuration (1-2 minutes)

    • Set up ingress and load balancing
    • Initialize monitoring
    • Validate deployment

Total time: 5-10 minutes for single server, 15-20 minutes for multi-server setup

Access Configuration​

Custom Domain Setup​

If using a custom domain, ensure your DNS is configured:

# Your DNS should point to the server(s)
permit.yourcompany.com → <server-ip>

# For multi-server, point to load balancer or all server IPs

IP-Based Access​

For simpler deployments, access directly via server IP:

# Single server
https://<server-ip>

# Multi-server (access any server)
https://<server-1-ip>
https://<server-2-ip>
https://<server-3-ip>

Post-Installation Verification​

Check Platform Status​

# Overall platform health
./scripts/status.sh

# Detailed service status
./scripts/status.sh --detailed

# Resource usage
./scripts/status.sh --resources

Verify Git Integration​

# Test Git connectivity
./scripts/test-git.sh

# Check policy sync status
./scripts/policy-status.sh

Test Web Access​

  1. Open your browser to the configured URL
  2. You should see the Permit Platform setup wizard
  3. Complete the initial organization setup

Configuration Options​

Resource Sizing​

Adjust resource allocation based on your needs:

# In configuration file
resources:
  backend:
    replicas: 5
    cpu: "1000m"
    memory: "2Gi"
  
  celery:
    replicas: 3
    cpu: "500m" 
    memory: "1Gi"
    
  database:
    cpu: "2000m"
    memory: "4Gi"
    storage: "200Gi"

Security Configuration​

# Enhanced security options
security:
  ssl_only: true
  strong_passwords: true
  audit_logging: true
  network_policies: true
  
certificates:
  auto_renew: true
  provider: "letsencrypt"  # or "custom"

Recovery and Rollback​

If Installation Fails​

# Clean up partial installation
sudo ./scripts/cleanup.sh

# Retry installation
sudo ./install.sh

Installation Logs​

# View installation logs
tail -f /var/log/permit-install.log

# Check specific component logs
./scripts/logs.sh k3s
./scripts/logs.sh platform

Installation complete? Continue to Management Guide to learn about day-to-day operations.

Contents