Self-Hosted Internal Tools for Teams
OpenRun provides a self-hosted PaaS-style workflow for internal tools without moving application code or data to a proprietary deployment service. Teams can deploy web apps to a private server or Kubernetes cluster with GitOps, SSO, RBAC and audit logging built in.
Teams replacing a low-code builder can build code-first internal tools with any AI coding tool; see OpenRun vs Retool, Appsmith and Budibase.
What you will set up on this page:
- A Linux machine behind the VPN with OpenRun installed as a systemd service
- Server configuration with OIDC login for every app and a GitHub token for source access
- Manually managed TLS certificates, since the node is not reachable from the public Internet
- RBAC grants that give each team its own set of apps
- An
apps.stardeclaration in git with a scheduled sync that creates and updates apps
Scenario
This use-case documents the scenario where you want to:
- Set up an instance to host web apps for use by your team in an enterprise
- The instance is behind a VPN, there is no inbound access over the public Internet
- Uses OIDC (or SAML) to manage access to the various apps
- Set up an automated GitOps workflow for app updates and new app creation
For this use case, we will use a GitHub account for source control.
Initial Setup
To get OpenRun running, the initial setup involves:
Create the machine
Create a Linux machine, accessible by your team through the VPN on port 443.
Create the DNS entry
Create a DNS entry pointing to the machine’s IP address, for example an A record for apps.example.com. A wildcard DNS entry *.apps.example.com will make it easier to install apps at the domain level.
Create the OIDC app
Create an OIDC app in the IdP console. Set up groups scope such that group info is available. Note the client ID and secret. The callback URL would be https://apps.example.com/_openrun/auth/oidc/callback.
Create a GitHub token
Create a GitHub Personal Access Token in GitHub settings. Set the scope to the repositories you want to use for your apps. Note the token. SSH key based auth is an alternative.
Installation
Install the native package and start the service:
sudo systemctl enable --now openrunBoth approaches create a user openrun and install the service under /var/lib/openrun.
To run containerized apps, ensure that Docker or Podman is installed and running on the machine:
- For Docker, the
openrunuser should be added to the docker group. - As
openrunuser, rundocker psorpodman psto verify that the container manager is functional.
Configuration
Change to the openrun account by running sudo su -l openrun. Edit the openrun config /var/lib/openrun/openrun.toml. Update it to have below contents (replace values which say CHANGEME):
[security]
admin_password_bcrypt = "$2a$10$L5dzoAEZFKmpdXbbbFddkurIP639w2.fl49737kmxxxxxxxx" # CHANGEME Retain orig value
callback_url = "https://apps.example.com" # CHANGEME: OAuth/OIDC/SAML callback URL prefix
app_default_auth_type = "oidc_okta" # Default auth for all apps
auth_required = true # Prevent unauthenticated apps from being served
default_git_auth = "githubpat" # Account used for all GitHub access
[system]
default_domain="apps.example.com" # CHANGEME: domain without protocol
[http]
host = "0.0.0.0"
port = 80
redirect_to_https = true
[https]
port = 443
# auto-TLS is not enabled since the node is not accessible over the public internet
[git_auth.githubpat]
user_id = "mygithubaccount" # CHANGEME
password = "github_pat_11A7FEN7Q0XPbzMWp2LxrF_emLLexxxxxxxxxxxx" # CHANGEME
[auth.oidc_okta]
key = "0oavknst5tcxxxxxx" # CHANGEME client ID
secret = "nBTsFRY9BUZ5aAQsbmHtbvkIAx_OnUyxoExxxxxxx" # CHANGEME client secret
discovery_url = "https://integrator-33xxxxx-admin.okta.com/.well-known/openid-configuration" # CHANGEME
scopes = ["openid", "profile", "email", "groups"]This config:
- Sets the default ports to 80 and 443
- Sets the apps to use OIDC for auth and requires every app to have authentication enabled
- Sets the GitHub PAT
- Leaves
admin_password_bcryptunused in this scenario; it can be kept at its original value or changed
As the regular user (since openrun user might not have sudo access), run sudo systemctl restart openrun to pick up the config update.
TLS Certificates
OpenRun supports automatic TLS certificates using TLS-ALPN on port 443 or HTTP-01 on port 80. Public certificate authorities must be able to reach the selected challenge port. For private deployments, use your own certificates or an internal ACME CA that can reach the server.
In this scenario, since the node is behind a VPN, TLS certs will have to be managed manually. Create the cert files and place them in /var/lib/openrun/config/certificates:
| Files | Used for |
|---|---|
default.crt and default.key | Default certificate file and key file for all domains |
example.com.pem and example.com.key | Certificate for the example.com domain |
RBAC Config
At this point, all apps are authenticated by OIDC, but every logged-in user can access all apps. To restrict which user has access to which apps, RBAC can be used. RBAC uses the dynamic config, which does not require restarting the OpenRun server. We will set up a RBAC schema where:
| Apps under | Available to |
|---|---|
/it | The IT team |
/engg | The engineering team |
/shared | Everyone |
| All other paths | Only the admin |
To set the RBAC config, change to the openrun account by running sudo su -l openrun. Edit /var/lib/openrun/config/dynamic_config.json to have:
{
"version_id": "ver_33erDLffhaXjgibPb5GRb3anN0V",
"rbac": {
"roles": {
"viewer": ["app:read", "app:access"],
"user": ["app:access"]
},
"grants": [
{
"description": "Admin has full access to all apps",
"users": ["group:admin"],
"roles": ["viewer"],
"targets": ["*:**"]
},
{
"description": "IT team has access to apps under /it",
"users": ["group:it"],
"roles": ["viewer"],
"targets": ["/it/**"]
},
{
"description": "Engineering team has access to apps under /engg",
"users": ["group:engineering"],
"roles": ["viewer"],
"targets": ["/engg/**"]
},
{
"description": "All logged in users can access the shared apps",
"users": ["regex:.*"],
"roles": ["user"],
"targets": ["/shared/**"]
}
]
}
}Group info is not defined in the config, it will come from the IdP. To update the RBAC config, run
openrun server update-config /var/lib/openrun/config/dynamic_config.jsonThis will upload the RBAC config to the metadata server (and also update the file on disk). Use the current version_id, or use the --force option to overwrite. The server is now ready for installing apps.
SAML instead of OIDC
If SAML needs to be used instead of OIDC, much of the setup remains the same. Create the SAML app in the IdP with these settings:
| IdP setting | Value |
|---|---|
| Single sign-on URL | https://apps.example.com/_openrun/sso/saml_okta_test/acs |
| Audience URI (SP Entity ID) | https://apps.example.com/_openrun/sso/saml_okta_test/metadata |
In the openrun.toml, instead of the [auth.oidc_okta] section, add a section like
[saml.okta_test]
metadata_url = "https://integrator-336XXXXX.okta.com/app/exkvzxe13XXXXX/sso/saml/metadata" # CHANGEMEand for app_default_auth_type, set the value to saml_okta_test. The IdP has to be configured to provide the group information under the groups attribute.
For both OIDC and SAML, in addition to the group info coming from the IdP, additional groups can be defined in the OpenRun RBAC config. The user names would have to be provided in the RBAC config, prefixed with the provider name, like oidc_okta:user1@example.com or saml_okta_test:user1@example.com.
App Installation
OpenRun supports installing apps using the imperative CLI interface or using the declarative config files. We will use the declarative approach here.
In one of the GitHub repos which is accessible using the PAT created above, create an app config file like
# Admin apps
app("/admin/disk_usage", "github.com/openrundev/apps/system/disk_usage")
app("/admin/memory_usage", "github.com/openrundev/apps/system/memory_usage")
app("/admin/audit", "github.com/openrundev/apps/openrun/audit_viewer")
# IT apps
app("/it/bookmarks", "github.com/openrundev/apps/utils/bookmarks")
app("/it/contacts", "github.com/openrundev/apps/utils/contacts")
# Engineering apps
# Install container based apps (python and go)
limits = {"cpus": "2", "memory": "512m"} # Set limits (optional)
app("/engg/streamlit_example", "github.com/streamlit/streamlit-example", git_branch="master",
spec="python-streamlit", container_opts=limits)
# shared apps: the RBAC grant on /shared/** makes these accessible to all logged in users
app("/shared/dictionary", "github.com/openrundev/apps/misc/dictionary")If this file is checked into the main branch in the myorg/myrepo repo, then running a command like
openrun sync schedule --minutes 1 --approve --promote github.com/myorg/myrepo/apps.starwill set up a sync which checks every minute for new updates to the file.
- RBAC applies to every app: who can reach an app is controlled by the
app:accessgrants, not by the app’s auth type. The grant on/shared/**makes those apps accessible to everyone who logs in via OIDC. - No unauthenticated apps: in this team setup,
auth_required = trueis enabled at the server level, soauth="none"apps are blocked from being served even if they are defined in app metadata. - New apps declared will be automatically created.
- Code changes in the repos referenced or config changes in the apps will also automatically be applied on the existing apps.
No further manual updates are required on the machine. All updates can be done by just checking in changes into the declarative config - Full GitOps CI/CD, in one command.
The operational tasks around these apps, restarts, re-runs and lookups, can be deployed the same way as actions, usable from a form, the CLI and by AI agents, in place of Jenkins or Rundeck jobs.
Frequently Asked Questions
What is a self-hosted internal tools platform?
A self-hosted internal tools platform runs a team’s internal web apps, dashboards and automation scripts on infrastructure the organization controls, instead of on a vendor’s cloud. The platform handles deployment, login, access control and auditing, so each app does not have to implement them. OpenRun is an open-source platform of this kind. It deploys apps from Git and adds SSO, RBAC and audit logs to every app.
How do you plan a self-hosted deployment of an internal tools platform?
Plan these items before installing:
- Where it runs: a single Linux server is enough for most teams. Use a Kubernetes cluster when apps need to scale out across nodes.
- Network access: decide whether the server is reachable only over the VPN or private network. On a private network, plan for a DNS entry and manually managed TLS certificates.
- Identity: pick the identity provider (OIDC or SAML, such as Okta or Microsoft Entra) and create an app registration for the platform.
- Access control: map identity provider groups to the app paths each team is allowed to use.
- Source control: keep the app declarations in a Git repo and create a read-only token for the platform.
- Operations: plan backups for the platform metadata and for app data, and decide how long to retain audit events.
The steps on this page implement this plan with OpenRun on one machine behind a VPN.
Does a self-hosted internal tools platform need Kubernetes?
No. OpenRun runs as a single binary on one Linux server and uses Docker or Podman to run app containers. Idle apps are stopped, so one server can host many internal tools. The same app declarations work on Kubernetes when horizontal scaling is needed.
How do internal apps get SSO, RBAC and audit logs without code changes?
OpenRun authenticates each request before it reaches the app. OIDC or SAML login is configured once at the server level and applies to every app. RBAC grants map identity provider groups to app paths. Every request and operation is recorded as an audit event.
Can the platform run in a private network or VPC with no inbound Internet access?
Yes. This page describes that setup. The server needs outbound access to fetch source code and container images, and to reach the identity provider. Inbound access from the public Internet is not required.