Skip to content
📌 OpenRun 1.0 is released, read the announcement
Self-Hosted Internal Tools for Teams

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.star declaration 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 openrun

Both 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 openrun user should be added to the docker group.
  • As openrun user, run docker ps or podman ps to 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):

/var/lib/openrun/openrun.toml
[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_bcrypt unused 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:

FilesUsed for
default.crt and default.keyDefault certificate file and key file for all domains
example.com.pem and example.com.keyCertificate 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 underAvailable to
/itThe IT team
/enggThe engineering team
/sharedEveryone
All other pathsOnly 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:

/var/lib/openrun/config/dynamic_config.json
{
  "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.json

This 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 settingValue
Single sign-on URLhttps://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

/var/lib/openrun/openrun.toml
[saml.okta_test]
metadata_url = "https://integrator-336XXXXX.okta.com/app/exkvzxe13XXXXX/sso/saml/metadata" # CHANGEME

and 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

apps.star
# 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.star

will 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:access grants, 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 = true is enabled at the server level, so auth="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:

  1. Where it runs: a single Linux server is enough for most teams. Use a Kubernetes cluster when apps need to scale out across nodes.
  2. 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.
  3. Identity: pick the identity provider (OIDC or SAML, such as Okta or Microsoft Entra) and create an app registration for the platform.
  4. Access control: map identity provider groups to the app paths each team is allowed to use.
  5. Source control: keep the app declarations in a Git repo and create a read-only token for the platform.
  6. 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.