Skip to main content

Self-Hosting Hikyaku

Hikyaku is open source. You can run it outside the hosted instance at app.hikyaku.org. Start on this page to install your own deployment.

If you did not read Architecture yet, read it first. It shows how the components below connect. It also gives the reason for some setup steps.

Self-Hosted vs. Hosted​

The hosted instance and a self-hosted instance use the same code. Both have the same features. The only difference is who operates the infrastructure.

Hosted (app.hikyaku.org)Self-hosted
SetupNone. Sign up and start.You provision all the components below
UpdatesHikyaku applies themYou monitor releases and upgrade each repository
DataIn the Supabase project of HikyakuIn infrastructure that you control
CustomizationStandard configurationFull access to change and redeploy all services
CostSubscriptionThe cost of your infrastructure (Supabase, compute, domains)

Use a self-hosted instance if you must control the location of your data, if you want to customize the platform, or if you want to add it to infrastructure that you operate.

Components​

ComponentRepositoryRuns onSetup guide
Dashboard & customer booking sitehikyakuVercel, or any Next.js hostWeb Frontend
Database, Auth, StorageSupabaseSupabase Cloud or a self-hosted Supabase projectSupabase Setup
Routing, optimisation, payments, schedulinghikyaku-apiDocker hostNestJS API
Spatial stack (Valhalla, VROOM, Photon)Included with hikyaku-apiDocker, on a private network with the APINestJS API
Driver apphikyaku-mobileAndroidMobile Setup
n8n integrationhikyaku-n8nYour n8n instancen8n Integration

Prerequisites​

  • Node.js 20+ and pnpm, to build and run the dashboard.
  • Docker, for the API and the spatial stack.
  • A Supabase project, on supabase.com or on a self-hosted Supabase instance.
  • A domain that you control. You need this only for subdomain-based customer booking sites (<tenant>.yourdomain.com). Refer to the TLS item in Before You Go to Production.
  • Access to the repositories that you deploy, in the hikyaku GitHub organization.

Setup Order​

  1. Set up Supabase. This step creates the database, the auth configuration, and the storage buckets. All other components need them.
  2. Deploy the web frontend. This is the dashboard and the customer booking site.
  3. Deploy the NestJS API. This includes routing, optimisation, payments, scheduling, and the spatial stack (Valhalla, VROOM, Photon).
  4. Set up the mobile app. Do this step only if drivers sign in from the field. At this time, the app is available only for Android.

To connect your n8n instance, refer to n8n Integration. Self-hosted operators must build their own copy of the node for their instance. That guide gives the procedure.

Before You Go to Production​

These items are different from the hosted instance:

caution

The spatial stack (Valhalla, VROOM, Photon) has no authentication. This is safe only because these containers publish no host ports. Only the private Docker network that they share with the API can reach them. Do not expose them on the LAN or the public internet.

  • Wildcard TLS for tenant subdomains. If you use only the path-based dashboard, skip this item. For subdomain-based booking sites, your hosting platform must issue a wildcard certificate for your domain. Most platforms cannot do this unless they control your nameservers. The hosted instance of Hikyaku uses a Cloudflare Worker to solve this problem. For more information, refer to Architecture → Why the Worker is necessary.
  • The first Valhalla boot is slow. Valhalla downloads a regional map extract and builds routing tiles before it answers requests. Until Valhalla is ready, VROOM and the API return errors. These errors are normal and do not show a crash.
  • Keep the Supabase service-role key on the server. This key bypasses all row-level security policies in the database. Put it in hikyaku-api. Do not put it in the client bundle of the web app.

Checklist​

Get Help​