Project

Local development

Run Inkspace from source, work on the database schema, and contribute.

Prerequisites

  • Node.js 22 or newer and npm
  • Docker Desktop or Docker Engine, for the local PostgreSQL database

Run from source

  1. Clone the repository and install dependencies:

    git clone https://github.com/ak4duy/inkspace.git
cd inkspace
npm install

  2. Create the local database Compose file from the development example, and replace PASSWORD_HERE with a password of your choice:

    cp docker/docker-compose.dev-example.yml docker/docker-compose.yml

    It runs postgres:16-alpine on 127.0.0.1:5433.

  3. Copy .env.example to .env and fill it in, using the same password:

    DATABASE_URL=postgresql://inkspace:PASSWORD_HERE@localhost:5433/inkspace
BETTER_AUTH_URL=http://localhost:6767
BETTER_AUTH_SECRET=generate-a-long-random-secret-for-local-dev

  4. Start PostgreSQL and sync the schema:

    npm run db:up
npm run db:sync

  5. Start the development server:

    npm run dev

The app runs at http://localhost:6767.

Scripts

Script What it does
npm run dev Next.js development server on port 6767
npm run build Production build
npm start Serve the production build on port 6767
npm test Run the test suite
npm run lint Lint the project
npm run db:up Start the local PostgreSQL container
npm run db:down Stop the local PostgreSQL container
npm run db:sync Pre-sync columns, then push lib/db/schema.ts to the database
npm run db:generate Generate SQL migrations with drizzle-kit
npm run db:studio Open Drizzle Studio

Project layout

Path Contents
app/ Next.js App Router pages, server actions and API routes
components/ React components, including the editor and the reader
lib/ Auth, database schema, i18n dictionaries, uploads and settings
docker/ Entrypoint, schema sync script and Compose examples
public/ Static assets and updates.json release notes
tests/ Unit tests
website/ This website — an Astro site deployed to GitHub Pages

Branches & releases

  • nightly is the development branch and publishes the nightly image.
  • master is the stable branch and publishes the latest image.
  • Tags matching v*.*.* publish versioned images.

CI runs the tests and a production build on every push and pull request to either branch.

Contributing

Bug reports and feature requests are welcome on GitHub Issues. For release notes, add an entry to public/updates.json — the app and this website’s changelog both read from it.

Working on this website

The website lives in website/ and is independent of the app:

cd website
npm install
npm run dev

Documentation pages are Markdown files in website/src/content/docs/. Pushes to master that touch the website or public/updates.json redeploy it to GitHub Pages.