From 0381363d4ed6fa474d2ee5a3cad746ec8e22942d Mon Sep 17 00:00:00 2001 From: Brian Fertig Date: Wed, 12 Aug 2026 12:05:56 -0600 Subject: [PATCH] Updates to README --- README.md | 190 ++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 169 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index e215bc4..a8af415 100644 --- a/README.md +++ b/README.md @@ -1,36 +1,184 @@ -This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app). +# Organize -## Getting Started +A self-hosted, installable PWA for staying organized: an extended to-do +list and notes organizer laid out as a Kanban-style board. -First, run the development server: +- **Categories** are the board's lanes (e.g. "To Do", "In Progress", "Done"). +- **Groups** are the cards within a lane — each has a color, a markdown + notes panel, and a to-do list, and can be dragged between lanes. +- **To-Dos** live inside a Group, with an optional details field. + +Accounts are required (there's no anonymous/local-only mode — the board +needs a database to persist to), and the first account ever created on a +given instance automatically becomes its administrator. + +## Features + +- Kanban board with drag-and-drop: reorder Categories, and drag Groups + between/within Categories +- Per-Group markdown notes and a to-do list with a completion progress + indicator +- Light/dark theme (follows system by default) +- Installable PWA (add-to-home-screen); requires a live connection to the + server for its database, so there's no offline mode +- Credentials-based accounts (email + password), with an Admin page to: + - change a user's role (Administrator / User / Pending), email, or + password, or delete their account + - control how the site handles new sign-ups (see [Sign-up modes](#sign-up-modes) + below) + +## Tech stack + +Next.js 16 (App Router) · React 19 · TypeScript · Tailwind CSS 4 · +PostgreSQL via Prisma 7 · Auth.js v5 (Credentials provider, JWT sessions) · +dnd-kit · base-ui + +## Quick start (Docker) + +This is the recommended way to run Organize. All you need is Docker with +the Compose plugin. + +1. **Clone the repo** + + ```bash + git clone https://git.brianfertig.com/brianfertig/Organize.git + cd Organize + ``` + +2. **Create your `.env`** + + ```bash + cp .env.example .env + ``` + + Then open `.env` and: + - Generate a real `AUTH_SECRET` (used to sign session cookies) — for + example with `openssl rand -base64 32` — and paste it in. + - Optionally change `POSTGRES_PASSWORD` from the placeholder. + + See [Configuration](#configuration) below for what each variable does. + +3. **Start everything** + + ```bash + docker compose up -d + ``` + + This builds the app image, starts Postgres, waits for it to be + healthy, then starts the app — which applies any pending database + migrations automatically on every boot before serving traffic. No + separate migration or setup step is needed. + +4. **Open the app** at [http://localhost:3000](http://localhost:3000) and + sign up. The very first account created becomes the site's + administrator; everyone after that follows whatever + [sign-up mode](#sign-up-modes) is currently set (Open, by default). + +### Updating ```bash -npm run dev -# or -yarn dev -# or -pnpm dev -# or -bun dev +git pull +docker compose up -d --build ``` -Open [http://localhost:3000](http://localhost:3000) with your browser to see the result. +`--build` matters here: without it, Compose will keep running whatever +image it already built and won't notice that the source changed. -You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file. +### Stopping -This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel. +```bash +docker compose down +``` -## Learn More +Postgres's data lives in `./data/postgres` on the host (a bind mount, not +a Docker volume), so it survives `docker compose down` — back up that +directory if you want a safety net before major upgrades. -To learn more about Next.js, take a look at the following resources: +## Configuration -- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API. -- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial. +All configuration is via environment variables, read from `.env` by +Docker Compose (see `.env.example` for the template). -You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome! +| Variable | Used by | Purpose | +| -------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------- | +| `AUTH_SECRET` | `app` | Encrypts/signs session cookies. Required in production — generate with `openssl rand -base64 32`. | +| `POSTGRES_USER` | `db` | Postgres superuser created on first init. | +| `POSTGRES_PASSWORD` | `db` | Password for `POSTGRES_USER`. Change this from the `.env.example` placeholder. | +| `POSTGRES_DB` | `db` | Database name created on first init. | +| `DATABASE_URL` | host-side tooling only | Prisma connection string for running things like `npx prisma studio` from your own machine. **Not** used by the `app` container itself — see note below. | -## Deploy on Vercel +> **Note on `DATABASE_URL`:** inside `docker-compose.yml`, the `app` +> service is given its own `DATABASE_URL` that points at the `db` service +> over the Compose network (`db:5432`), built from the `POSTGRES_*` +> variables — it ignores the `DATABASE_URL` in `.env`. The `.env` value +> (pointed at `localhost:5432`) is only there for convenience if you want +> to run Prisma commands, or the app itself, directly on the host. Since +> the bundled `db` service doesn't publish port 5432 to the host by +> default, that only works once you either add a `ports: ["5432:5432"]` +> mapping to the `db` service, or point `DATABASE_URL` at a Postgres +> instance you're running yourself. -The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js. +## Sign-up modes -Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details. +The Admin page (`/admin`, administrators only) has a "New sign-ups" +setting with four modes: + +- **Open** (default) — anyone can sign up and immediately gets the `User` + role. +- **Approved** — anyone can sign up, but starts as `Pending` and can't log + in until an administrator changes their role to `User` or + `Administrator`. +- **Confirmed** — *not implemented yet* (shown disabled in the UI); + intended to gate new accounts on email confirmation instead of manual + approval. +- **Closed** — sign-ups are turned off entirely: the sign-up form and any + links to it are removed, and the sign-up action itself refuses new + accounts even if called directly. + +The very first account on a fresh instance always becomes an +administrator, regardless of the current sign-up mode — otherwise there'd +be no one able to approve anyone. + +## Local development (without Docker) + +Running the app directly on your host is mainly useful for editing code +with hot reload. You'll still need a Postgres instance it can reach. + +1. **Node 24** (matching the Docker image; no `engines` field enforces this, but it's what's tested) and `npm install`. +2. **A reachable Postgres.** The simplest option is to add a port mapping + to the `db` service in `docker-compose.yml` (`ports: ["5432:5432"]`) + and run just that service: `docker compose up -d db`. Then set + `DATABASE_URL` in `.env` to match (the `.env.example` default of + `postgresql://organize:organize@localhost:5432/organize` will work as-is + if you keep the default Postgres credentials). +3. **Apply migrations:** + ```bash + npx prisma migrate dev + ``` + Against a fresh database this also runs `prisma/seed.ts` automatically, + creating `dev@example.com` / `password123` as an administrator with a + small sample board. If it doesn't (e.g. you'd already applied every + migration before), run `npx prisma db seed` to trigger it explicitly. + Don't run either against a database you care about. +4. **Run the dev server:** + ```bash + npm run dev + ``` + Open [http://localhost:3000](http://localhost:3000). + +Other useful scripts: `npm run build` (production build), `npm run start` +(serve a production build), `npm run lint`. + +## Project structure + +``` +app/ Next.js App Router routes: (app) is the signed-in board + admin, + (auth) is login/signup +components/board/ The Kanban board: categories, groups, to-dos, drag-and-drop +components/admin/ Admin page: user table, role menu, sign-up mode settings +lib/actions/ Server Actions (auth, categories, groups, todos, notes, admin) +lib/ Shared server helpers (db client, auth helpers, settings, colors) +prisma/ Schema, migrations, and the dev-only seed script +auth.ts Auth.js configuration (Credentials provider, JWT session callbacks) +proxy.ts Route protection (redirects signed-out users to /login, etc.) +```