# About DevList.app

DevList.app is a hand-curated directory of software engineering resources.
It runs on the [Suprnova directory starter](https://github.com/eas4ai/suprnova-directory-starter),
a free, MIT-licensed directory application built on the
[Suprnova](https://suprnova.app) Rust framework, with Vue pages rendered on
the server. The starter brings what every directory needs: owner
submissions, moderation, search, categories, articles, SEO controls and free
or paid publication. DevList.app adds its own features on top.

Here is how to build your own directory from the starter, from an empty
folder to a site you can put online.

## 1. Install the tools

- **Rust 1.94 or newer** builds the server and the console commands.
- **Bun** installs and builds the frontend.
- **Node 24** runs the page renderer and generates your key.
- **A C toolchain, pkg-config and the OpenSSL headers** compile the native
  libraries. On Debian or Ubuntu: `sudo apt install build-essential pkg-config libssl-dev`.
- **Git** fetches the code.

## 2. Get the code

```sh
git clone https://github.com/eas4ai/suprnova-directory-starter.git my-directory
cd my-directory
```

## 3. Configure it

```sh
cp .env.example .env
node -e 'const fs=require("node:fs"); const crypto=require("node:crypto"); const p=".env"; fs.writeFileSync(p,fs.readFileSync(p,"utf8").replace(/^APP_KEY=.*$/m,"APP_KEY="+crypto.randomBytes(32).toString("base64url")))'
```

The second command writes a random `APP_KEY` into `.env`. The key protects
sessions and saved payment settings: keep it safe, and never change it on a
live site.

Open `.env` and give your directory a name with `APP_NAME` and a one-sentence
`SITE_DESCRIPTION`, which search results and social previews show. Leave
`APP_URL` at `http://localhost:8765` for now. The database is SQLite in
`database.db`, so there is no database server to run.

## 4. Build it

```sh
cargo build --locked --bins
cd frontend
bun install --frozen-lockfile
bun run build
bun run build:ssr
cd ..
cargo run --locked --bin directory -- migrate
```

The first build takes a few minutes while Cargo compiles the dependencies.
You get two programs: `directory`, the web server, and `console`, for one-off
commands. `migrate` creates the tables; run it again after an update and it
applies only what is new.

## 5. Run it

The site runs as three processes. Start each in its own terminal, from the
project folder:

```sh
cd frontend && bun run dev
```

```sh
node --env-file=.env frontend/bootstrap/ssr/ssr.js
```

```sh
cargo run --locked --bin directory -- serve --no-migrate
```

The first is Vite, which serves the frontend while you work on it. The
second renders the public pages on the server, so visitors and search
engines get the full page before any script runs. The third is the
application. Open [localhost:8765](http://localhost:8765): the directory is
there, empty.

## 6. Catch the email

Creating an account sends a verification link, and `.env` sends mail to a
local catcher on port 1025. Run one, for example Mailpit:

```sh
docker run --rm -p 1025:1025 -p 8025:8025 axllent/mailpit
```

Its inbox is at [localhost:8025](http://localhost:8025).

## 7. Fill it and take charge

```sh
cargo run --locked --bin console -- directory:categories
```

This creates the starter's categories. To try a full directory first,
`directory:demo` adds demo listings and articles; keep those in a
demonstration copy, not in the directory you will publish.

Register at `/register`, open the verification link from the mail catcher,
and find your account ID on **Your account**. Then make yourself the
administrator, with your own ID:

```sh
cargo run --locked --bin console -- admin:access grant --user-id 1
```

**Administration** now appears in the menu. A new directory has no
publishing plan yet, so create one: open **Publishing plans**, choose **New
plan**, give it the identifier `free` and a name, pick the billing type
**Free** with an amount of 0, tick **Offer this plan to owners** and choose
**Create plan**. Then submit a listing from **Your listings**, approve it in
**Listing reviews**, choose the free plan, and it is public.

## 8. Make it yours

`SITE_THEME` picks a color preset (`zinc`, `blue`, `indigo`, `violet`,
`emerald`, `teal`, `rose` or `orange`); leave it blank and `SITE_ACCENT` sets
your own accent color. `SITE_LOGO_URL` points at your logo. The pages are Vue
components in `frontend/src/pages`, so everything else is yours to change.

## 9. Put it online

In production, set `APP_ENV=production`, `APP_DEBUG=false`, your real
`APP_URL`, `SESSION_SECURE=true` and `SESSION_COOKIE_PREFIX=__Host-`; keep
the database and `DIRECTORY_MEDIA_ROOT` outside the release folder; and send
mail through a real SMTP relay with your own sender. Build the release,
run `migrate` once, then keep the application and the page renderer running
under a supervisor such as systemd, behind a reverse proxy that serves HTTPS.
Back up the database, the media folder and the key together.

DevList.app runs exactly this, packed into one container image with its
database on a persistent volume.

Questions about DevList.app go to our
[support tracker](https://github.com/eas4ai/devlist-support/issues).