Get started with Hopya

Hopya is an open-source home for your team’s tasks, documents, tables, and more. Run it on infrastructure you control, or contact WNZN to discuss a cloud or managed setup. This documentation is for the self-hosted application, not the marketing site’s Cloudflare deployment.

Early release: evaluate the workflows you need, read the security guide, and keep verified backups before using Hopya for important work.

Before you start

Before you start: reference table
Requirement	Setup
Tools	Git, Docker Engine, Docker Compose; Node.js 24 for standard initializer
Application	One replica; PostgreSQL does not enable multi-replica support
SQLite	Local persistent storage, not NFS
Initializer	Private configuration only; no default account or overwrite of existing `.env`

Install your instance

git clone https://github.com/wnzn/hopya.git
cd hopya
npm run init:env
docker compose up -d --build --wait

Docker-only initializer, without host Node.js

After cloning and entering the repository:

docker run --rm --network none --read-only --cap-drop ALL \
  --security-opt no-new-privileges:true --user "$(id -u):$(id -g)" \
  -v "$PWD:/work" -w /work node:24-bookworm-slim \
  node --experimental-strip-types ops/init-env.ts
docker compose up -d --build --wait

The default proxy listens on 127.0.0.1:8888. Application data and local files live in ./data. Do not publish the private API or web service ports.

Create the first account

Open http://localhost:8888 on the server.
Use SETUP_TOKEN from private generated .env to create first site administrator.
Keep that token out of chat, issue reports, this site, and source control.

If you are opening Hopya from another device, first configure a trusted HTTPS reverse proxy and the exact APP_URL using the deployment guide. Do not disable same-origin checks to make a proxy work.

Give your work a home

Open Work and create a workspace.
Add a standalone List, or create a Project and a list inside it. Tasks always belong to lists.
Create your first task with a title, and optionally an assignee, dates, checklist, or custom fields.
Try List, Board, Calendar, Gallery, and Timeline. They show the same tasks; switching view does not duplicate them.
Add Documents for written context and Tables for structured records.

Workspaces are permission boundaries. Existing accounts must be added by a workspace owner; becoming a site administrator or signing in through SSO does not grant access to every workspace.

Choose your next guide

Using Hopya explains editing, collaboration, views, settings, and conflict recovery.
Plan work with your team turns the basics into a practical shared workflow.
Connect notes and structured data covers Documents and Tables together.
API quick start explains tokens, workspace-scoped requests, pagination, and safe writes.
Self-hosting and deployment covers configuration, HTTPS, PostgreSQL, storage, upgrades, and full backups.

Keep a recovery path

Workspace exports contain portable records and file metadata, not all accounts, secrets, or file bytes. They are not complete backups. Follow backup and restore, store encrypted backups off-host, and rehearse recovery.