Install and Administer Apps – Documentation and Support | Knowi

Configure access, source repositories, and a Knowi Apps installation for development or for running packaged Apps.

Permissions

App permissions control actions; App sharing controls which Apps a user can access. An administrator does not automatically see every App. Editing a shared App requires write access to it as well as the relevant permission.

Permission	Allows
`apps:view`	Open the Apps area and see owned and shared Apps.
`apps:edit`	Create, edit, build, preview, import, export, and manage App settings.
`apps:publish`	Publish, roll back, and apply live access, menu, or custom-domain changes. Embedding also requires `apps:edit`.
`apps:share`	Share an App with users and groups.
`apps:delete`	Remove an App.

Dataset and dashboard bindings also require access to those assets. Saving a write action requires App edit permission, write access to the App, edit access to its destination datasource, and DBWrite enabled for the account. See Write actions.

Choose where the source lives

Apps created for development use a Git repository. Each built version records its source revision. Imported packages contain a built App and can run without a repository; change the source in development and import a new package to update them.

A dedicated repository per App keeps source and releases easy to manage. Repository collaborator access and App sharing are separate.

Repository setup

On New app, open Advanced settings > Repository. An existing App shows its repository and branch under App settings > Repository. Only options enabled for the installation appear.

Option	Setup
Knowi-managed	Enter a name and choose Create repository. Knowi creates a private repository.
GitHub	Choose Connect GitHub, authorize the repositories Knowi may use, then select Check again.
Other Git (SSH)	Enter the remote and optional branch, generate a deploy key, add it to the repository with write access, then select Verify.

Knowi-managed repositories

Names use 3-60 lowercase letters, numbers, and hyphens.

Account administrators who can edit Apps can give GitHub users access to a Knowi-managed repository by username:

On New app, Manage access appears after you create the repository and starts on Read and write.
After the App exists, use Share code under App settings > Repository, which starts on Read only. See Share App code.

GitHub emails each person an invite, and Invite pending shows until they accept. Access to GitHub and Other Git (SSH) repositories is managed in GitHub or on your Git host, not in Knowi.

On a customer installation, managed repositories use a GitHub organization and GitHub App owned by that customer. Configure GITHUB_HOSTING_ORG, GITHUB_HOSTING_APP_ID, GITHUB_HOSTING_INSTALLATION_ID, and GITHUB_HOSTING_KEY_FILE in the installer. The GitHub App needs repository Administration and Contents read/write permissions, with Metadata read access.

GitHub

The GitHub administrator chooses which repositories the Knowi GitHub App can access. Source changes through Knowi or MCP require write access. Update the GitHub selection and choose Check again to change the available repositories.

Customer installations configure their own GitHub App and OAuth credentials using the GITHUB_APP_* and GITHUB_CLIENT_* settings. Use <Knowi URL>/apps/manage/git/oauth as the callback URL and <Knowi URL>/apps/manage/git/callback as the setup URL. Enable user authorization during installation. Set GITHUB_HOST for GitHub Enterprise Server. Follow the release bundle's README for the complete registration steps; Knowi's cloud GitHub Apps are not used on customer installations.

Other Git over SSH

Use an SSH remote such as git@host:group/repo.git or ssh://git@host/group/repo.git. Leave the branch empty to use the default branch. Add the generated public deploy key to that repository with write access, then select Verify. Knowi checks access and shows the pinned host-key fingerprints. A read-only key stays pending.

Operators enable SSH with GIT_SSH=1 and can restrict destinations with GIT_ALLOWED_HOSTS. Users do not supply Git passwords or personal access tokens.

AI provider

Local source editing, repository builds, and package imports do not require AI generation. Building through an MCP coding client does not invoke a second Knowi coding agent.

The Knowi Builder's AI generation uses an external provider. Users can configure their provider and API key under AI Settings for Apps. Generation sends the key with its request; the Apps cluster does not store it. An App's own ai.generate feature is separate: it still requires an enabled AI service, a configured provider, and available credit on the target where the App runs.

Choose an installation mode

Use the versioned Knowi Apps bundle supplied with your release. It installs Apps services into Kubernetes and connects them to your Knowi server.

Mode	Use it for	Installed services
`APPS_MODE=full`	Development, Git builds, and optional AI generation.	Runtime, gateway and service images, storage, builder, generator, and development proxies.
`APPS_MODE=serve`	A target that imports and runs signed, prebuilt Apps.	Runtime, gateway and service images, and storage. No builder, generator, AI proxy, or npm proxy.

Serving mode needs no Git credentials or generation AI key. It can publish imported versions, map target data, save target secrets, and import updates. It cannot edit source or build Apps. This restriction does not disable an installed App's declared AI feature; configure that separately if required.

Installation requirements

Kubernetes 1.28 or later, with a network plugin that enforces NetworkPolicy.
ingress-nginx using IngressClass nginx in namespace ingress-nginx.
ReadWriteMany storage for artifacts.
Wildcard Apps DNS and a matching TLS certificate, for example *.apps.example.com.
Node.js 20 or later, kubectl, and openssl on the installation workstation.
For managed App databases, PostgreSQL 14 or later with TLS and a provisioning user with CREATEDB and CREATEROLE. Set POSTGRES=none when no App needs a managed database.

The supplied installer targets Kubernetes. On AWS, use an EKS or other Kubernetes cluster that meets these requirements. An existing Knowi server on EC2 can connect to it. The bundle is not an ECS or standalone EC2 installer, and a package does not contain Kubernetes or the Apps runtime.

gVisor is recommended for App isolation. Set RUNTIME_CLASS to the RuntimeClass installed in your cluster. Confirm that the nodes eligible for that class have the CPU architecture selected below. This check applies to the customer's cluster, regardless of where the package was built.

Match the target platform

APP_PLATFORM defaults to linux/amd64. App packages, runtime images, and eligible runtime nodes must agree. The builder also schedules builds for that architecture.

For an ARM cluster, such as one using AWS Graviton, use linux/arm64 only with release images that support it and rebuild the App for that platform. Changing the configuration does not convert a package or its native dependencies. A mismatched package is rejected.

Check node architecture before installing:

kubectl get nodes -L kubernetes.io/arch,kubernetes.io/os
kubectl get runtimeclass

If using a sandbox RuntimeClass, also check its scheduling settings and the nodes configured to run it. A class name alone does not establish architecture support.

Install and connect Knowi

From the supplied release directory:

cp apps.conf.example apps.conf

Set the domains, Knowi URL, allowed Core source addresses, image registry and version, storage, platform, and database settings. Configure Git only for development. Then run:

bash install.sh apps.conf

The installer checks the cluster, creates service tokens, applies the configuration, and waits for services. It preserves generated keys in knowi-apps-state/ beside the configuration file. Back up that folder and restrict access to it.

For an external Knowi server:

Add the generated knowi-apps-state/cloud9.properties settings to Knowi's configuration.
Mount the package key files at the configured paths on every Knowi server that handles Apps requests. See Package signing and trust.
If using the generated private certificate authority, add its ca.crt to Knowi's Java truststore and users' browsers. Otherwise supply a trusted certificate.
Restart Knowi.

The installer supports a single-machine minikube evaluation through apps.laptop.conf and --minikube; follow the release README for its Docker, memory, DNS, and certificate setup. This is separate from the production cluster prerequisites.

Serving mode needs access to the Knowi server, its image registry or local mirror, and the connections used by installed Apps. Full mode also needs the selected Git, npm, and AI endpoints. The installer does not support a corporate HTTP proxy.

Package signing and trust

Apps move between accounts and installations in two ways. Export to another account needs no signing setup, because it uses the installation's own signature and artifact store. Export to another server produces a signed ZIP with the complete built App. It needs package signing and verification keys, a compatible Core and runtime, and a build that records its target platform. See Export a package for what each export contains.

Full mode generates a persistent RSA signing key and its public verification key unless PACKAGE_SIGNING_KEY_FILE supplies an existing private key. Package keys are separate from service and session tokens. Do not share those tokens between installations.

On the source, mount the private key for Knowi and set appsPackageSigningKeyFile. Keep it readable only by the Knowi process. Copy only the public verification key to the target through your approved channel. On the target, set:

APPS_MODE=serve
PACKAGE_VERIFICATION_KEY_FILE=path/to/package-verification.pem

The generated Core settings use appsPackageVerificationKeyFile for the public key path. The default mount directory is /etc/knowi-apps. A custom private key must be RSA in PKCS8 PEM format; the public key must be a PEM PUBLIC KEY (SPKI). Serving mode rejects a private signing key.

The target trusts packages signed by the configured key. Do not modify the exported ZIP. Knowi verifies the signature, contents, and platform before installing it. Retain the source key for future updates; changing the trusted public key changes which packages the target accepts.

Core's reverse proxy must allow at least 260 MiB request bodies and 300-second package transfers. The bundle configures its package ingress and minikube Core ingress; configure an external Core proxy yourself.

Develop in one environment and run in another

Use full mode in development. Write source locally or generate it in Knowi, then build for the target platform.
Configure the target in serving mode with the approved public verification key.
Export with Export to another server, import on the target, and repeat the export and import to update it. The steps, data mapping, and what a package does and does not carry are in Copy and Move Apps.

The target must provide each feature the App requires:

Managed database schemas need managed PostgreSQL enabled; POSTGRES=none refuses them.
PDF export and reports need the browser renderer installed on Knowi. Sending reports also needs email configuration and user permissions.
AI features need the target AI service and provider configuration, even when source generation is disabled.
HTTP, workspace, and write-action connections need target configuration and permissions. A package does not copy their credentials.

Update safely

Use matching Core and Apps releases. A combined bundle pins their versions together; an Apps-only update does not upgrade an existing Knowi server. Use the release's versioned images rather than latest.

Update the runtime first and wait until it is ready. Then update builder configuration and builder/generator deployments. An older runtime can reject output from the new builder. The installer enforces this sequence. Keep the same order for manual or GitOps updates; applying all output from --render at once does not enforce it.

Older Apps can continue running. Rebuild an older version with the new builder before exporting it as a complete ZIP if it lacks platform metadata. Plain JSON export for another account in the same installation remains available.

To convert full mode to serving mode, first set appsGenerationEnabled=false in Knowi and restart it. Wait for builds to finish, then rerun the installer with APPS_MODE=serve and the public verification key. The installer refuses conversion while builds are active and removes its authoring resources while keeping storage and databases. GitOps operators must remove the old authoring resources themselves after reviewing the installer's resource list.

Custom domains

An App keeps its standard address, such as https://orders.apps.knowi.com, when you add a domain you own, such as orders.example.com.

Open App settings > URL & domain. Under Custom domain, enter the hostname and select Save.
Add the DNS TXT record shown in Knowi at _knowi-verify.<domain>, then select Verify. Use the exact displayed value. If DNS has not propagated, wait and verify again.
Add a CNAME for the domain pointing to the target shown in Knowi. On the default cloud installation this is domains.apps.knowi.com; other installations use their configured Apps domain.

Type	Name	Value
TXT	`_knowi-verify.orders.example.com`	The verification token shown in Knowi.
CNAME	`orders.example.com`	The routing target shown in Knowi.

Verification republishes a live App to add the domain. TLS certificate issuance can take a few minutes after DNS is correct; wait for a valid certificate before sharing the address. An unpublished App uses the domain after its next publish. Knowi sign-in works on the custom domain, with a separate session for each domain. Preview keeps its preview address.

A root domain such as example.com cannot use a standard CNAME. Use your DNS provider's supported ALIAS, ANAME, or flattening option for the shown target. If that is unavailable, use a subdomain and redirect the root to it, or ask Knowi support for a supported DNS target.

Change replaces the domain and requires TXT verification again. Remove detaches it after the live App is republished; the standard App address remains available.

Limits and permissions:

One custom domain per App, and one App per domain across the installation. An unverified claim can be taken by another App after 72 hours; verified domains are not released this way.
Knowi-owned domains, the installation's Apps domain, and IP addresses are rejected.
Saving requires App edit permission. Verifying a live App, or changing or removing its verified domain, also requires publish permission.
Customer installations must configure KNOWI_APPS_K8S_CUSTOM_DOMAIN_ISSUER. Without a certificate issuer, verifying a live App reports that custom domains are not enabled, leaves the domain pending, and keeps the standard address working. Saving a domain alone does not contact the runtime.

On-premises and GitHub Enterprise Server

Use your installation's Apps domain in place of cloud addresses shown in examples. See Custom domains for DNS and certificate requirements.

GitHub Enterprise Server is supported when configured through GITHUB_HOST; Git over SSH is another option. Both belong in the development environment and are unnecessary on a serving-only target.

View as user needs matching Core and runtime support. Update the runtime gateway before enabling the Core feature so the identity banner, expiry, and activity exclusions are available.

Technical troubleshooting

Problem	Check
Export to another server is missing	Mount the source private key and set `appsPackageSigningKeyFile` on every Knowi server handling export, then restart Knowi. For copies within one installation, use Export to another account.
Moving apps between servers isn't set up here	The Knowi log names the missing setting: `appsPackageSigningKeyFile` on the source, `appsPackageVerificationKeyFile` on the target.
Export says the App was built before export to another server was available	The version was built before the builder recorded its target platform. Update the runtime, then the builder. Then publish a new version of the App and export it.
Import says the package isn't from a trusted server	Check that the target has the source's public verification key and the ZIP has not been modified.
Package platform does not match	Rebuild for the target architecture. Check release image support and node scheduling.
Package upload is rejected or times out	Check body-size and timeout limits on both the Core proxy and Apps package ingress.
A required capability is unavailable	Enable the required target service or remove that feature in development and export a new version.
Build or edit controls are absent	Check App permissions and installation mode. Serving mode intentionally accepts package updates without source editing.
App or build pods stay Pending	Check eligible Linux node architecture, sandbox RuntimeClass, storage, resource capacity, and image pull access.