Updates to README
This commit is contained in:
Brian Fertig
parent
ce1d540444
commit
0381363d4e
190
README.md
190
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
|
```bash
|
||||||
npm run dev
|
git clone https://git.brianfertig.com/brianfertig/Organize.git
|
||||||
# or
|
cd Organize
|
||||||
yarn dev
|
|
||||||
# or
|
|
||||||
pnpm dev
|
|
||||||
# or
|
|
||||||
bun dev
|
|
||||||
```
|
```
|
||||||
|
|
||||||
Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
|
2. **Create your `.env`**
|
||||||
|
|
||||||
You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
|
```bash
|
||||||
|
cp .env.example .env
|
||||||
|
```
|
||||||
|
|
||||||
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.
|
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.
|
||||||
|
|
||||||
## Learn More
|
See [Configuration](#configuration) below for what each variable does.
|
||||||
|
|
||||||
To learn more about Next.js, take a look at the following resources:
|
3. **Start everything**
|
||||||
|
|
||||||
- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
|
```bash
|
||||||
- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
|
docker compose up -d
|
||||||
|
```
|
||||||
|
|
||||||
You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
|
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.
|
||||||
|
|
||||||
## Deploy on Vercel
|
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).
|
||||||
|
|
||||||
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.
|
### Updating
|
||||||
|
|
||||||
Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
|
```bash
|
||||||
|
git pull
|
||||||
|
docker compose up -d --build
|
||||||
|
```
|
||||||
|
|
||||||
|
`--build` matters here: without it, Compose will keep running whatever
|
||||||
|
image it already built and won't notice that the source changed.
|
||||||
|
|
||||||
|
### Stopping
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker compose down
|
||||||
|
```
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
All configuration is via environment variables, read from `.env` by
|
||||||
|
Docker Compose (see `.env.example` for the template).
|
||||||
|
|
||||||
|
| 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. |
|
||||||
|
|
||||||
|
> **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.
|
||||||
|
|
||||||
|
## Sign-up modes
|
||||||
|
|
||||||
|
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.)
|
||||||
|
```
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue