Skip to main content

On-premises quick start

Install the self-hosted Permit Platform with default settings. This page is for operators who have a prepared cluster and want the shortest path to a running platform. The installation guide covers every option and explains each step.

Enterprise on-premises license required

The on-premises installer is available to Enterprise customers with an on-premises license. To get a license, contact Permit.io.

Prerequisites​

Complete the on-premises prerequisites first. You need:

  • A Kubernetes or OpenShift cluster with at least 8 CPU cores, 32 GB of RAM, and 100 GB of storage.
  • A Git repository for policies (GitHub, GitLab, or Bitbucket) with an SSH deploy key that has write access.
  • kubectl and helm on your workstation, plus docker to push images to a registry.
  • A container registry that the cluster can pull from, unless you use the OpenShift internal registry.
  • The installer package from the download link Permit.io sends you.

1. Extract the installer package​

# Download the package (using your provided link)
tar -xzf permit-platform-on-prem-installer.tar.gz
cd permit-platform-on-prem-installer

2. Set the required values​

Open charts/permit-platform/values.yaml and replace the three placeholders:

# Edit configuration file (REQUIRED)
vi charts/permit-platform/values.yaml

# Replace ALL placeholders with your actual values:
# 1. CHANGEME_FRONTEND_DOMAIN → your domain (e.g., app.company.com)
# 2. CHANGEME_GIT_REPO_URL → your Git repository URL
# 3. CHANGEME_SSH_PRIVATE_KEY → your SSH private key content
PlaceholderReplace with
CHANGEME_FRONTEND_DOMAINThe domain users open in a browser, for example app.company.com
CHANGEME_GIT_REPO_URLThe SSH URL of your policy repository
CHANGEME_SSH_PRIVATE_KEYThe private key of the repository's deploy key

After the change, the values look like this:

global:
  frontendDomain: "app.company.com"  # Replace CHANGEME_FRONTEND_DOMAIN

permitServices:
  policySync:
    policyRepoUrl: "git@github.com:your-org/policies.git"  # Replace CHANGEME_GIT_REPO_URL
    sshPrivateKey: |  # Replace CHANGEME_SSH_PRIVATE_KEY
      -----BEGIN OPENSSH PRIVATE KEY-----
      b3BlbnNzaC1rZXktdjEAAAAABG5vbmUAAAAEbm9uZQAAAAA...
      -----END OPENSSH PRIVATE KEY-----
The installer stops on unreplaced placeholders

If values.yaml still contains CHANGEME_FRONTEND_DOMAIN, CHANGEME_GIT_REPO_URL, or CHANGEME_SSH_PRIVATE_KEY, the installer exits before it deploys anything. Keep the | after sshPrivateKey:. Without it, the Helm install fails because the key is no longer multi-line.

3. Push the images to your registry​

Skip this step on OpenShift when you use the OpenShift internal registry.

On other targets, the installer exits when global.imageRegistry in values.yaml is empty. Push the images from the package to your registry. The push script also sets imageRegistry to the registry path:

# Push all images to your registry (run from installer directory)
./scripts/push-images-to-registry.sh us-central1-docker.pkg.dev/project/repo  # GKE/GAR
# or
./scripts/push-images-to-registry.sh artifactory.company.com/permit         # Artifactory

For a registry that needs a username and password, such as Artifactory or Harbor, create an image pull secret before you install. See Add credentials for a registry that requires authentication.

4. Run the installer​

If you pushed the images in step 3, run the installer with --skip-images and the flag for your cluster:

# IMPORTANT: Use --skip-images since images are already in your registry!

# For GKE, EKS, AKS, or other Kubernetes with private registry:
./scripts/install-permit-platform.sh --gke --skip-images

# For OpenShift with private registry:
./scripts/install-permit-platform.sh --openshift --skip-openshift-registry --skip-images

If you use the OpenShift internal registry, or Kind for local testing, run the installer without --skip-images:

# Red Hat OpenShift (ROSA, OCP, OpenShift Dedicated) with the internal registry
./scripts/install-permit-platform.sh --openshift

# Local development with Kind cluster (testing only)
./scripts/install-permit-platform.sh --kind

# See all available options and help
./scripts/install-permit-platform.sh --help

The installation guide describes every flag.

5. Verify the installation​

When the installer finishes, it prints the frontend URL and the admin credentials:

[SUCCESS] 🎉 Permit Platform On-Prem deployed successfully!

[INFO] Access your Permit Platform at:
[INFO]   • Frontend: https://your-configured-domain.com
[INFO]     - Admin user: admin/[Generated Password]
[INFO]     - Or register a new account

[INFO] Additional services:
[INFO]   • OpenSearch Dashboard: https://your-configured-domain.com/opensearch/ (no authentication required)
[INFO]   • RabbitMQ Dashboard: https://your-configured-domain.com/rabbitmq/ (permit/[Generated Password])
[INFO]   • Keycloak Admin: https://your-configured-domain.com/auth (admin/[Generated Password])
[INFO]   • SCIM Service: https://your-configured-domain.com/scim

[INFO] Important:
[INFO]   • For Kind clusters (development), add to /etc/hosts:
[INFO]     127.0.0.1 your-configured-domain.com

Check that every pod in the namespace shows Running, then open https://<your-frontend-domain> and sign in as admin with the password from the output. The platform prompts you to create your first organization and project.

On a Kind cluster, add the domain to /etc/hosts as the output shows.

Commands for checking the deployment​

# Check all services status
kubectl get pods -n permit-platform

# View installation progress  
kubectl get events -n permit-platform --sort-by='.lastTimestamp' --watch

# View logs for specific services
kubectl logs -f deployment/permit-backend-v2 -n permit-platform
kubectl logs -f deployment/permit-frontend -n permit-platform
kubectl logs -f deployment/keycloak -n permit-platform

# Check ingress and networking
kubectl get svc,ingress -n permit-platform

# Uninstall platform (if needed)
helm uninstall permit-platform third-party-services migrations -n permit-platform
kubectl delete namespace permit-platform
Deleting the namespace deletes the platform data

kubectl delete namespace permit-platform removes the PostgreSQL, OpenSearch, and Keycloak persistent volume claims in the namespace. Depending on your storage class reclaim policy, the policies, users, and decision logs are deleted with them. Back up first. See the on-premises management guide.

Next steps​

For installation help, email support@permit.io or ask in the Permit community on Slack.

Contents

Edit this page

Need help?