Self-Hosted Web Apps on a VPS
This guide turns a Linux VPS (virtual private server) into a self-hosted platform for personal web apps. OpenRun manages application deployment, GitOps updates, HTTPS certificates and authenticated access while Docker or Podman runs each application.
What you will set up on this page:
- A publicly reachable VPS with OpenRun installed as a systemd service
- Server configuration with Google login for every app, automatic TLS certificates and a GitHub token for source access
- RBAC grants that give family and friends their 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 OpenRun on a Linux VPS or server to host web apps for yourself, family and friends
- Use an OAuth provider like Google for login
- Set up an automated GitOps workflow for app updates and new app creation
For this use case, we will use a Google OAuth account for authentication and a GitHub account for source control.
Initial Setup
To get OpenRun running, the initial setup involves:
Create the server
Create a Linux VPS or server that is publicly accessible 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 Google OAuth client
Create a Google OAuth by visiting Google Console. The callback URL would be https://apps.example.com/_openrun/auth/google/callback. Note the client ID and secret.
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.
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 = "google" # Default auth for all apps
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
service_email = "contact@example.com" # CHANGEME: email address for registering with Let's Encrypt. Set a value to enable automatic certs
use_staging = false # whether to use Let's Encrypt staging server
[git_auth.githubpat]
user_id = "mygithubaccount" # CHANGEME
password = "github_pat_11A7FEN7Q0XPbzMWp2LxrF_emLLexxxxxxxxxxxx" # CHANGEME
[auth.google]
key = "37019xxxxx-u8e2lltb1tmxxxxxx.apps.googleusercontent.com" # CHANGEME
secret = "GOCSPX-ybUAedirQiexxxxxxxxxx" # CHANGEMEThis config:
- Sets the default ports to 80 and 443
- Sets the apps to use Google for auth
- Sets the GitHub PAT
- Enables automatic TLS cert creation
- 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.
RBAC Config
At this point, all apps are authenticated by the Google OAuth account, but anyone with a Google account can access the apps. To restrict which user has access to what 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 | Shared with |
|---|---|
/family | Family members |
/shared | Family members and friends |
| 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": {
"groups": {
"admin": ["google:me@example.com"],
"family": ["google:family1@example.com", "google:family2@example.com"],
"friends": ["group:family", "google:friend1@example.com", "google:friend2@example.com"]
},
"roles": {
"viewer": ["app:read", "app:access"],
"user": ["app:access"]
},
"grants": [
{
"description": "Admin has full access to all apps",
"users": ["group:admin"],
"roles": ["viewer"],
"targets": ["all"]
},
{
"description": "Family has access to apps under /family",
"users": ["group:family"],
"roles": ["viewer"],
"targets": ["/family/**"]
},
{
"description": "Family and friends have access to apps under /shared",
"users": ["group:friends"],
"roles": ["user"],
"targets": ["/shared/**"]
}
]
}
}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.
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")
# Family apps
app("/family/bookmarks", "github.com/openrundev/apps/utils/bookmarks")
app("/family/contacts", "github.com/openrundev/apps/utils/contacts")
# Friends apps
app("/friends/dictionary", "github.com/openrundev/apps/misc/dictionary")
# Install container based apps (python and go)
limits = {"cpus": "2", "memory": "512m"} # Set limits (optional)
app("/friends/streamlit_example", "github.com/streamlit/streamlit-example", git_branch="master",
spec="python-streamlit", container_opts=limits)If this file is checked into the main branch in the myuser/myrepo repo, then running a command like
openrun sync schedule --minutes 1 --approve --promote github.com/myuser/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. - Apps for everyone who can log in: add a grant like the
/shared/**one with"users": ["regex:.*"]. - Apps without login: if
auth="none"is used, no login is required for the app, and with RBAC enabled theanonymoususer needs anapp:accessgrant on it. - 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.