Skip to content
Pricing Download Open app
DocsDevelopersSelf-Hosting

Developers

Self-Hosting Both

Community Edition and self-hosting are not yet publicly released. Existing operators can continue managing their installations using Docker Compose. The self-hosted container stack runs the exact same codebase and backend services as the managed cloud deployment.

Stack Architecture

  • API Backend: Node.js 22 + Express 5 + Prisma ORM.
  • Database: PostgreSQL 16+.
  • Cache & Queues: Redis for pub/sub, caching and Socket.io presence events.
  • Web Frontend: React 18 + Vite PWA.

Hardware Requirements

  • Docker Engine 28+ and Docker Compose v2
  • Minimum 2 CPU cores and 4 GB RAM
  • 20 GB disk space for database volumes and snapshot archives

Quick Start reference for existing installations

  1. Clone the repository and enter the directory. Check the Docker host before starting the stack: 
    sh scripts/selfhost-verify.sh --engine
    Docker Engine versions before 28 can expose localhost-published ports to the same layer-2 network. Upgrade the engine before using this setup; see Docker port-publishing security.
  2. Copy .env.selfhosted.example to .env.selfhosted. Set the database and Redis credentials, public app URL, authentication secrets and mail delivery settings. Use URL-safe passwords for the connection URLs. Pin TAPTIDY_IMAGE_TAG to the released version you intend to run.
  3. Initialize the database and seed the built-in settings and templates: 
    docker compose --env-file .env.selfhosted -f docker-compose.selfhosted.yml run --rm app sh ./scripts/self-host-init.sh
    This uses Prisma db push; it does not execute migration data transformations. Review release-specific upgrade instructions and back up existing databases before updating. Never add --accept-data-loss to make an upgrade proceed.
  4. Start the standalone stack: 
    docker compose --env-file .env.selfhosted -f docker-compose.selfhosted.yml up -d
  5. Check startup, database and Redis from inside the app container: 
    docker compose --env-file .env.selfhosted -f docker-compose.selfhosted.yml exec app sh ./scripts/selfhost-verify.sh
    The script also runs on a host with Node.js 22, accepting an HTTP(S) origin as its first argument. Passing probes does not verify registration, email, task synchronization or backup restoration; test these separately.
  6. Open http://localhost:3000 and register an account. Configure and test email delivery before inviting other users.

The app binds to loopback by default. For public access, set TAPTIDY_DOMAIN and use the optional TLS proxy overlay: 

docker compose --env-file .env.selfhosted -f docker-compose.selfhosted.yml -f docker-compose.selfhosted.proxy.yml up -d
Keep APP_BIND_ADDRESS unset so the app port cannot bypass the proxy. A LAN-only installation can explicitly select a private interface address.

docker compose down preserves data volumes; docker compose down -v deletes them. Keep database backups outside these volumes and verify a restoration before relying on them.

Minimum environment configuration

In the copied example, replace the password placeholders and generate a separate value with openssl rand -hex 32 for each secret below. The Compose file builds DATABASE_URL and REDIS_URL from these inputs; do not duplicate those connection URLs in the environment file.

POSTGRES_USER=taptidy
POSTGRES_DB=taptidy
POSTGRES_PASSWORD=replace-with-url-safe-password
REDIS_PASSWORD=replace-with-another-url-safe-password
APP_URL=http://localhost:3000
AUTH_SECRET=replace-with-generated-secret
ENCRYPTION_KEY=replace-with-generated-64-hex-secret
EMAIL_SECRETS_KEY=replace-with-another-generated-64-hex-secret
TAPTIDY_EDITION=community
TAPTIDY_IMAGE_TAG=replace-with-released-version
ALLOW_NO_SMTP=true

For a public TLS deployment, set TAPTIDY_DOMAIN and change APP_URL to that HTTPS origin. Without SMTP, email verification and password reset are unavailable. Configure and test mail before relying on them.

Community features and paid services

The standalone Compose stack sets TAPTIDY_EDITION=community. This enables locally operated features without a TapTidy Cloud subscription: sync, households, integrations, encryption, reports and backup capabilities. It disables cloud billing and promotional subscription jobs. Authentication, ownership checks and the family notice requirements still apply.

Existing clients receive the internal Pro capability tier; this does not create a paid subscription or make your account an administrator. The web subscription screen identifies community self-hosting. External email, AI, push, storage and integration services still need the operator's own configuration and credentials, and those providers may charge separately.

Other deployments remain in cloud mode unless their operator explicitly sets TAPTIDY_EDITION=community and restarts the server. Restart every app/worker process together; do not mix editions against one database.

Self-Hosted Considerations

  • Push Notifications: Native FCM push requires configuring your own Firebase project credentials. Android devices can also use WebSocket push sync (De-Googled flavor).
  • Updates: The Android app update checker queries the official TapTidy releases endpoint to ensure mobile clients stay up-to-date even when connecting to self-hosted backends.

Private family servers and child access

TapTidy Cloud does not offer child accounts. Before restarting an existing server on this version, back up the database and run the database initialization command in the Quick Start to sync the new consent and PIN-session columns. Self-hosted Compose skips startup migrations. To enable child PIN profiles on your own private family server, keep TAPTIDY_EDITION=community and set TAPTIDY_FAMILY_MODE=true in your self-hosted environment file. Recreate all app processes with the Compose command above. The flag defaults to false and cannot enable children on a Cloud deployment.

  1. Register an adult account on your family server and create a household.
  2. Open the household Members tab and choose Add child. Read the family notice and confirm you are the parent or legal guardian before entering a nickname and PIN.
  3. For an existing child, open their member controls and accept the current family notice. Older notices do not enable access.
  4. Use the family server's web PIN sign-in, or configure the Android app to connect to that same server before child sign-in.
  5. From the child member controls, withdraw consent to suspend further online access. Restoring access requires a new notice acceptance and a new PIN login; old tokens remain invalid.

This records a parent declaration; it does not independently verify identity, require a paid verification provider, or certify legal compliance. It is intended for parents operating their own family's service, not a public child-hosting business. The operator controls access, backups, retention, configured integrations and applicable legal duties. Email delivery is optional for this declaration; configure it if you need account recovery or invitations.

Withdrawal retains the profile and household history. Removing a child is a separate action. Neither action remotely erases data already downloaded to a device or retained in backups. Keep backups private and define a retention schedule.

Review external services before use. Google-flavor Android builds use Google services; the no-Google direct build uses Socket.IO sync. Direct-build update checks and explicitly configured integrations may contact external services. A self-hosted server is not a guarantee of zero external network traffic.

Future standalone child mode

A child mode that runs entirely on one device without any server is future work. The current family household system requires a family server for account creation, consent changes and PIN authentication; offline caches are not a standalone account system.