Skip to content

⭐️⭐️⭐️ Open-source, self-hosted alternative to Linear and Plane. Project management and issue tracking where teams and AI agents work side by side to plan and ship products.

docs: rework the README header and lead the Coolify guide with the published images (#698)

Croffccca9d094d69
diff --git a/README.md b/README.md
index 1934e9c3..fd3c217d 100644
--- a/README.md
+++ b/README.md
@@ -2,18 +2,19 @@
<img src="assets/banner.png" alt="It's a Plan — open-source project management and issue tracking where people and AI agents ship together" width="100%" />
-### Open-source alternative to Linear, Jira, Trello, and Plane, with AI agents built in
+# The open-source Linear alternative<br>where AI agents work as teammates
-Self-hosted project management and issue tracking. The difference: AI agents work here like any
-teammate — and everything is available over the REST API, webhooks, and MCP.
+Self-hosted project management and issue tracking, with no per-seat fees. Agents take issues on
+the same board as your people. Everything is available over the REST API, webhooks, and MCP.
+Replaces Linear, Jira, Asana, Trello, Plane, and Miro.
-If It's a Plan looks useful to you, star the repo ⭐ — it helps other people find it.
+If It's a Plan looks useful to you, star the repo ⭐ and
+[leave a review on Product Hunt](https://www.producthunt.com/products/it-s-a-plan/reviews).
<a href="https://railway.com/deploy/its-a-plan?referralCode=lQ5O6i&utm_medium=integration&utm_source=button&utm_campaign=itsaplan"><img src="https://railway.com/button.svg" alt="Deploy on Railway" height="40" /></a>
<a href="docs/coolify.md"><img src="assets/coolify-button.svg" alt="Deploy on Coolify" height="40" /></a>
<a href="docs/self-hosting.md"><img src="assets/docker-button.svg" alt="Self-host with Docker" height="40" /></a>
-
-[Website](https://itsaplan.dev) · [Pro](https://itsaplan.dev/pro) · [Discussions](https://github.com/croffasia/itsaplan/discussions) · [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md) · [Leave a review](https://www.producthunt.com/products/it-s-a-plan/reviews/new?utm_source=badge-product_review&utm_medium=badge)
+<a href="https://itsaplan.dev/pro"><img src="assets/pro-button.svg" alt="Deploy Pro version" height="40" /></a>
[![License: AGPL v3](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](LICENSE)
[![CI](https://github.com/croffasia/itsaplan/actions/workflows/ci.yml/badge.svg)](https://github.com/croffasia/itsaplan/actions/workflows/ci.yml)
@@ -42,25 +43,14 @@ own API keys — no per-seat fees, no lock-in.
It's a Plan is under active development. Expect breaking changes before the first stable
release.
-## How to help
-
-1. **Star the repo** if you think more people should see it. That is the whole cost, and it
- is what makes the project findable.
-2. **Share it** — post it on social media or send it to a colleague who runs a team or
- writes code. One link reaches people search never will.
-3. **Contribute.** Issues, bug reports, and pull requests are all welcome — start with
- [CONTRIBUTING.md](CONTRIBUTING.md).
-4. **Buy Pro.** The license pays for the work on the free Community edition, and your
- instance gets the [Pro features](#pro-edition) in return —
- [pricing and license terms](https://itsaplan.dev/pro).
-
## Features
| Area | What you get |
| --------- | ------------------------------------------------------------------------------------- |
| Product management | Kanban, table, timeline, and calendar views · cycles · custom fields · dashboards · docs · notes boards |
| AI agents | Agents as project members · internal on any model, or external on your coding CLI · runs start on an @mention, an assignment, or a schedule |
-| Platform | REST API with OpenAPI · MCP server · webhooks · pull requests from 5 forges · passkeys and Google sign-in · 12 languages |
+| Platform | REST API with OpenAPI · MCP server · webhooks · pull requests from 5 forges · passkeys and Google sign-in |
+| 13 languages | English · Ukrainian · Russian · Simplified Chinese · Traditional Chinese · Arabic · Persian · French · Portuguese (Brazil) · Indonesian · Spanish · Korean · Turkish |
<details>
<summary><b>Product management</b> — the full list</summary>
@@ -112,7 +102,6 @@ release.
- Outgoing webhooks: subscribe to events, signed payloads, and retries with a delivery log
- Sign in with an email or a username and a password, a passkey, or Google
- Notifications by email (SMTP or Resend) and Telegram, with per-member preferences
-- Interface in English, Ukrainian, Russian, Simplified Chinese, Traditional Chinese (Taiwan), Arabic, Persian, French, Portuguese (Brazil), Bahasa Indonesia, Spanish (Spain), Korean, and Turkish
- Instance administration: storage limits, mail transport, and instance-wide settings
</details>
diff --git a/assets/pro-button.svg b/assets/pro-button.svg
new file mode 100644
index 00000000..705cb185
--- /dev/null
+++ b/assets/pro-button.svg
@@ -0,0 +1 @@
+<svg width="192" height="40" viewBox="0 0 192 40" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M0 6a6 6 0 0 1 6-6h180a6 6 0 0 1 6 6v28a6 6 0 0 1-6 6H6a6 6 0 0 1-6-6V6Z" fill="url(#pro-bg)"/><g transform="translate(14 10) scale(0.8333)" fill="#fff"><path d="M12 17.27 18.18 21l-1.64-7.03L22 9.24l-7.19-.61L12 2 9.19 8.63 2 9.24l5.46 4.73L5.82 21z"/></g><text x="44" y="25.5" font-family="-apple-system,BlinkMacSystemFont,Segoe UI,Helvetica,Arial,sans-serif" font-size="14" font-weight="600" fill="#fff">Deploy Pro version</text><defs><linearGradient id="pro-bg" x1="190" y1="0" x2="27" y2="37.5" gradientUnits="userSpaceOnUse"><stop stop-color="#F59E0B"/><stop offset="1" stop-color="#C2410C"/></linearGradient></defs></svg>
diff --git a/docs/coolify.md b/docs/coolify.md
index f5f1eb63..e7b3acd4 100644
--- a/docs/coolify.md
+++ b/docs/coolify.md
@@ -1,54 +1,39 @@
# Deploy on Coolify
-[Coolify](https://coolify.io) builds the stack from source and generates the secrets itself,
-so the setup is a resource, a branch, and two domains.
+[Coolify](https://coolify.io) runs the stack from the Docker images published to GHCR on each
+release and generates the secrets itself. Nothing is built on your server, so the setup is a
+pasted compose file and two domains.
-## 1. Create the application
+## 1. Create the service
-**New Resource → Public Repository**, then pick the server to deploy on.
+**New Resource → Docker Compose Empty**, then pick the server to deploy on.
-Enter the repository URL and press **Check repository**:
+Paste the whole of one file into **Docker Compose file** and press **Save**:
-```
-https://github.com/croffasia/itsaplan.git
-```
+| Edition | File |
+| ------------------- | -------------------------------------------------------------------------- |
+| Pro (recommended) | [`docker-compose.coolify-pro.yml`](../docker-compose.coolify-pro.yml) |
+| Community | [`docker-compose.coolify-images.yml`](../docker-compose.coolify-images.yml) |
-Fill in the rest and press **Continue**:
+Without a license key the Pro images run as Community does. To unlock the Pro features later,
+enter the key in god mode, under **License**. The stack stays the same, with no move to
+another compose file.
-| Field | Value |
-| ---------------------- | ----------------------------- |
-| Build Pack | Docker Compose |
-| Base Directory | `/` |
-| Docker Compose Location| `/docker-compose.coolify.yml` |
+## 2. Set the domains
-## 2. Choose the branch
+The stack serves two origins: the api and the web app. Coolify generates a domain for each on
+the first deploy. To use your own, edit the domain of the `api` and the `web` service:
-The application starts on `main`. Change it in **Configuration → Git Source**: set
-**Branch**, leave **Commit SHA** as `HEAD`, and press **Save**.
-
-| Branch | What you get |
-| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `release` | released versions only. A mirror branch the release workflow moves to each published release. It appears with the first published release; until then there is nothing to deploy from. |
-| `main` | the latest features, the moment they merge. Expect breaking changes between releases. |
-
-## 3. Set the domains
-
-The stack serves two origins: the api and the web app. Both are set in
-**Configuration → General**, one field per service, and each needs the container port after
-the host:
-
-| Field | Example |
-| --------------- | ------------------------------- |
-| Domains for api | `https://api.example.com:3000` |
-| Domains for web | `https://plan.example.com:3001` |
+| Service | Example |
+| ------- | -------------------------- |
+| api | `https://api.example.com` |
+| web | `https://plan.example.com` |
Coolify turns those into `SERVICE_URL_API` and `SERVICE_URL_WEB`, which the compose file
reads as the api's `API_URL` / `APP_URL` and as the api origin web hands to the browser.
+Changing a domain later takes a redeploy, which is how Coolify applies an environment change.
-Changing a domain later takes a redeploy, which is how Coolify applies an environment
-change.
-
-## 4. Deploy
+## 3. Deploy
Press **Deploy**. Postgres, RustFS, api, worker, bot, and web come up together; the
one-shot `migrate` service applies the migrations first, and api, worker and bot start once
@@ -57,25 +42,36 @@ it exits. The first account registered becomes the instance admin.
Secrets (database password, auth secret, encryption key, worker token, object store credentials)
are generated on the first deploy and stay stable across later ones — nothing to fill in by
hand. Optional variables from `.env.example` — legal document URLs, telemetry opt-out,
-worker tuning — go in **Configuration → Environment Variables**.
+worker tuning — go in **Environment Variables**.
+
+## Upgrade
+
+Press **Redeploy**. Coolify pulls the newest images, and the `migrate` service backs up the
+database into the `db-backups` volume and applies the new migrations before the apps start.
+
+## Build from source
+
+Use this to run a branch instead of a release. The server builds the images itself, which
+takes longer and needs more memory than pulling them.
-## 5. Deploy the published images
+1. **New Resource → Public Repository**, then pick the server. Enter
+ `https://github.com/croffasia/itsaplan.git` and press **Check repository**.
+2. Set **Build Pack** to `Docker Compose`, **Base Directory** to `/`, and **Docker Compose
+ Location** to `/docker-compose.coolify.yml`, then press **Continue**.
+3. In **Configuration → Git Source**, set **Branch**, leave **Commit SHA** as `HEAD`, and press
+ **Save**:
-A Public Repository resource always builds from source. To run the images published to GHCR
-on each release, create the stack as a service instead.
+ | Branch | What you get |
+ | --------- | -------------------------------------------------------------------------------------------------- |
+ | `release` | released versions only. A mirror branch the release workflow moves to each published release. |
+ | `main` | the latest features, the moment they merge. Expect breaking changes between releases. |
-1. **New Resource → Docker Compose Empty**, then pick the server.
-2. Paste the whole of `docker-compose.coolify-images.yml` into **Docker Compose file** and
- press **Save**. It carries no `build:` sections — nothing is built. For the Pro edition,
- paste `docker-compose.coolify-pro.yml` instead. Without a valid license the Pro images run
- as the core does; the license key is entered in god mode, under **License**.
-3. In **Environment Variables**, set `VERSION` to a release (e.g. `0.10.1`); leave it out for
- the newest.
-4. Press **Deploy**. Coolify generates a domain for api and one for web on the first
- deploy; rename them under the service if you want your own.
+4. Set the domains in **Configuration → General**. Here each field needs the container port
+ after the host: **Domains for api** `https://api.example.com:3000`, **Domains for web**
+ `https://plan.example.com:3001`. Then press **Deploy**.
-To keep an existing Public Repository resource and pull instead of build, set **Custom build
-command** in **Configuration → General** to `docker compose pull` and redeploy.
+To keep a Public Repository resource and pull the published images instead of building, set
+**Custom build command** in **Configuration → General** to `docker compose pull` and redeploy.
To run the same stack outside Coolify, see [self-hosting.md](self-hosting.md) or
[railway.md](railway.md).