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
|
||||
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.)
|
||||
```
|
||||
|
|
|
|||
Loading…
Reference in New Issue