Deploy It's a Plan

Deploy and Host It's a Plan on Railway

It's a Plan is an open-source, self-hosted project management and issue tracking application for teams and AI agents. It provides configurable boards, cycles, initiatives, documents, dashboards, REST and MCP APIs, webhooks, and notifications. This template includes the browser interface, backend, background services, persistent PostgreSQL, and attachment storage on Railway.

About Hosting It's a Plan on Railway

This Docker-only template runs the upstream application images at version 1.7.0. A Caddy gateway serves the web interface and API from one HTTPS hostname. PostgreSQL stores application data, and a Railway S3-compatible bucket stores attachments. The API applies database migrations through its original image command.

Tech Stack

• Bun, Turborepo, and Elysia for the backend and background services.
• Next.js with server-side rendering, React, shadcn/ui, and Tailwind CSS.
• better-auth for email/password authentication and optional identity providers.
• Drizzle ORM and PostgreSQL 18.
• Railway S3-compatible object storage and Caddy 2.10.2.

Why Deploy It's a Plan on Railway

Railway provides HTTPS, private service networking, persistent database volumes, generated secrets, and object storage. The template pulls published Docker images without building source. Its gateway allows authentication on a generated Railway domain, so a custom domain is optional.

Common Use Cases

• Track software issues, releases, cycles, and product initiatives.
• Organize team work using boards, documents, and dashboards.
• Connect AI agents through REST APIs and MCP.
• Deliver webhook notifications and optional Telegram messages.

Deployment Notes

Open the gateway domain after all services become healthy. Its public port is 8080; the web application listens on 3001, and the API listens on 3000. The gateway strips the leading /api before forwarding API requests. Authentication therefore uses /api/api/auth/*. Background workers and the Telegram bot have no public listener and no PORT variable.

Register your own account on the first visit. The first registered account becomes the instance administrator. Upstream has no preset administrator credentials or supported administrator bootstrap username/password environment variables. Configure SMTP, AI provider credentials, and the Telegram bot token in the application interface. The bot remains idle until configured; keep exactly one replica.

The gateway is the intended browser entry point. api.API_URL=https://${{gateway.RAILWAY_PUBLIC_DOMAIN}}/api and api.APP_URL=https://${{gateway.RAILWAY_PUBLIC_DOMAIN}} use one hostname, allowing secure host-only session cookies. web.API_URL references api.API_URL. The generated API and web domains are diagnostic endpoints. To use a custom domain, attach it to the gateway and update the API's API_URL and APP_URL to that hostname; API_URL must retain /api.

Preserve BETTER_AUTH_SECRET and APP_ENCRYPTION_KEY; each is generated with ${{secret(64)}}. The worker and bot reference the API encryption key. PostgreSQL generates its own password, and all application services reference Postgres.DATABASE_URL. Changing an established encryption key prevents stored credentials from being decrypted.

Persist PostgreSQL at /var/lib/postgresql/data with PGDATA=/var/lib/postgresql/data/pgdata. Persist pre-migration dumps on the API's /backups volume, with BACKUP_RETENTION_DAYS=30. The API image includes PostgreSQL client tools and retains its original migration-and-server command. Web, worker, and bot require no application volume.

Create the native Railway bucket named attachments; it is included in the published template. The API references its ENDPOINT, BUCKET, ACCESS_KEY_ID, SECRET_ACCESS_KEY, and REGION variables. S3_FORCE_PATH_STYLE=false enables Railway's virtual-host addressing. The worker references the same API S3 configuration. Bucket credentials must remain references, never copied literal keys.

Required variable defaults and references:

Keep the supplied Caddy start command; it reads CADDY_CONFIG from standard input. All four application services and PostgreSQL use their image defaults. Initial worker or bot polls can retry while the API applies the first database migrations. Image tags are pinned; upgrade application images together after reviewing the release notes.

The verified deployment is available here. Verification covered service status, startup logs, sign-in and session persistence, an authenticated homepage, database reads, and attachment upload/download through both the API and web media route. Temporary verification data was removed.

Upstream: GitHub repository. See Railway bucket variables, Caddy startup options, and upstream hosting documentation.

Dependencies for It's a Plan on Railway

The gateway connects to the web and API services over Railway's private network. The API, worker, and bot share PostgreSQL; the API and worker share the attachment bucket. Two volumes preserve database data and pre-migration backups. The native bucket is a required managed resource in addition to the Docker services.

Deployment Dependencies