Deploy and Host self hosted Oxynote (Live Docs Wiki) on Railway

This template deploys one Oxynote service with embedded PostgreSQL and a persistent volume, so live charts sit beside the text that explains them. This is an independent onepush-dev packaging template, not an endorsed or official upstream listing.

About Hosting Oxynote open-source software on Railway (self hosted Oxynote template)

This template runs one Oxynote service built from the onepush-dev packaging of the pinned upstream 0.9.3 image, with PostgreSQL 18 embedded in the same container and a persistent volume at /oxynote/data.

Railway handles the HTTPS domain, restarts and the volume. ADMIN_PASSWORD is read only on first boot, so changing it later does not reset the existing admin account password.

Why Deploy Oxynote, the open-source technical documentation workspace on Railway (Railway Free Trial)

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying Oxynote on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.

Railway vs Other Hosting Providers and VPS for Oxynote self hosting

A VPS means you run the Docker host, volume backups and upgrades yourself, while Railway handles the infrastructure layer.

Provider	What You Get with Railway	What You Get with the Other Provider
DigitalOcean	A running Oxynote service with a public domain, a persistent volume and generated admin credentials.	Full control of a Droplet, where you install Docker, set the public URL and keep the host patched.
AWS	A one click deployment with the volume and domain already wired, and no IAM or VPC setup.	Fine-grained networking and storage control, assembled and maintained by you.
Hetzner	A managed deployment of the pinned Oxynote image with variables set in the Railway dashboard.	Low cost bare servers where you run the container, handle TLS and back up the volume on your schedule.

Common Use Cases for hosted Oxynote

Runbooks with live Prometheus charts: An on-call engineer opens a runbook with Live Metrics blocks querying Prometheus, so the chart sits beside the fix steps.
SQL-backed operational pages: A team keeps a page running read-only PostgreSQL, MySQL or MariaDB queries, showing queue depths beside notes on healthy values.
Reviewing docs and charts as one change: An engineer edits a threshold explanation and its chart in one draft, and a reviewer approves both in a single diff.
Internal API documentation: A platform team documents internal endpoints with request and response details and live example data.
Agent access over MCP: An AI coding agent reads and edits the same Oxynote pages through MCP over HTTPS.

Dependencies for Oxynote Docker hosted on Railway

This template runs one Oxynote service built from the onepush-dev image, which wraps the pinned upstream 0.9.3 release.

Deployment Dependencies for Managed Oxynote Service (one Oxynote service with embedded PostgreSQL 18 and a persistent volume)

The template creates one service with a public domain on port 8080, a health check on /login, and a volume mounted at /oxynote/data.

Variable	Type	Purpose
ADMIN_PASSWORD	Secret, 32 characters	Password for admin@example.com, generated on deploy.
OXYNOTE_PUBLIC_URL	Derived	Set to https://${{RAILWAY_PUBLIC_DOMAIN}} for links and MCP.

Optional settings are added by you on the service, not as template variables: OXYNOTE_SMTP_DSN with OXYNOTE_EMAIL_FROM_ADDRESS for mail, OXYNOTE_CRASH_REPORTING_DISABLED=true to opt out of crash reports, and OXYNOTE_DB_DSN for an external database.

Implementation Details for Oxynote (Using onepush-dev packaging based on the pinned upstream 0.9.3 image)

The image is ghcr.io/onepush-dev/oxynote:0.9.3, built from the upstream image pinned by digest.

How does Oxynote compare against other tools

Oxynote vs Grafana (Grafana Alternative)

Scope: Grafana focuses on observability dashboards, while Oxynote does not yet provide logs or alerting. Oxynote does not replace those yet.
Explanation: A Live Metrics block sits beside the prose that explains it, so both are reviewed together.
Charts: Oxynote runs Prometheus and SQL queries inside the page, which covers dashboard-style grids without a separate tool.

Oxynote vs Notion (Notion Alternative)

Hosting: Notion is a hosted workspace with a polished editor and a large ecosystem. Oxynote is self-hosted on your own infrastructure, which suits teams that want their documentation under their own control.
Live metrics: Oxynote renders metric charts from your own data sources on the page itself, rather than embedding a panel from another tool.
Review: Page edits go through a draft, a diff and an approval, like a pull request.

Oxynote vs BookStack (BookStack Alternative)

Focus: BookStack is a mature self-hosted wiki for general documentation. Oxynote is aimed at technical teams who run systems and want charts beside runbooks.
Charts and queries: Oxynote adds Live Metrics blocks and SQL-backed pages, which BookStack does not center on.
Maturity: BookStack is an established self-hosted wiki. Oxynote is newer than BookStack.

Oxynote with Docker on a VPS vs Oxynote on Railway (Oxynote Deployment Comparison)

Setup: Docker on a VPS means you manage the host, the volume and the reverse proxy yourself. The Railway template provisions the service, domain and volume for you.
Admin password: The upstream image uses a public default login that you must change before exposing it. This template generates a random ADMIN_PASSWORD in Variables.
Control: A VPS gives you full control over the host and networking. Railway trades some of that control for less operational work.

How to use Oxynote on Railway?

Work through these steps on your first day after the deploy finishes.

Open the public domain Railway assigned to the Oxynote service.
Sign in as admin@example.com using the ADMIN_PASSWORD value from the service's Variables tab.
Configure SMTP before you change the admin email, since example.com addresses cannot receive mail and a new address is otherwise confirmed only by link.
Rename the randomly named workspace under Settings so your team recognises it.
If you skip SMTP, use the "Copy invitation link" option to send invites by hand.
Add a Prometheus or SQL data source, then place a Live Metrics block on a page.
Make that page reviewable, so later edits go through a draft, a diff and an approval.

Check availability with a request to the login route.

curl -I https://your-domain/login

How to self host Oxynote on other VPS Services (Oxynote self hosting guide)

Clone the Repository

Clone the upstream repository from GitHub and move into its directory.

git clone https://github.com/oxynote/oxynote.git
cd oxynote

Install Dependencies

On a plain VPS you need Docker installed and running.

Configure Environment Variables

Upstream's default login is admin@example.com with the public default password, which you must change before exposure. Until you add an authenticated TLS proxy and change that password, publish the port only on localhost, because the stock password is public.

Start the Oxynote Application

Run the upstream image with port 8080 published and the data volume mounted at /oxynote/data, so your workspace survives restarts.

docker run -d --name oxynote \
  -p 127.0.0.1:8080:8080 \
  -v oxynote_data:/oxynote/data \
  ghcr.io/oxynote/oxynote:latest

Railway handles the HTTPS domain, persistent volume and the generated admin password for you, so none of these manual steps are needed there. This independent template packaging is not an endorsed upstream listing.

Official Pricing of Oxynote (Oxynote pricing)

Oxynote is Apache-2.0 open-source software and free to self-host. You pay only for the infrastructure you run, plus any model or mail provider you add.

Oxynote hosted vs self hosted comparison (Pricing, features, costs, and more)

The pinned upstream README describes no hosted Oxynote service, so you choose between Railway and your own VPS.

Monthly cost of self hosting Oxynote on Railway

Railway bills by usage, so your monthly cost depends on the RAM and CPU the service uses, the size of the persistent volume holding the embedded PostgreSQL database, and any extra services you attach.

System Requirements for Hosting Oxynote on a VPS

On a VPS you need a Linux host with Docker, enough memory and disk for the container and its data volume, and a public domain with HTTPS if you want the MCP server to work for AI agents.

Frequently Asked Questions (FAQs)

Where is the admin password?

The generated admin password is stored in the Oxynote service's Variables tab as ADMIN_PASSWORD, and you sign in as admin@example.com with it.

Can anyone sign up?

No. Without SMTP configured, use the "Copy invitation link" option and share the link yourself.

Does this replace Grafana alerts?

No. Keep your alerting in the tools you already run.

Can AI agents connect?

Yes, MCP clients such as Claude Code and Codex can connect, but the MCP server requires HTTPS.

What must be backed up?

Back up the entire volume mounted at /oxynote/data, since it holds the embedded PostgreSQL database, secrets, and the search index. Restore from those backups has not been tested on Railway.

Why did an extra OXYNOTE variable stop startup?

Oxynote rejects any OXYNOTE_* variable it does not recognize, and the boot fails when one is present.