# Firehose

Willem's personal blog — a modular static blog built on [Blogex](./blogex/), powered by Phoenix and NimblePublisher.

Posts live as markdown files in git and compile into the BEAM at build time: zero database, zero runtime I/O, sub-millisecond reads.

The project structure is modular, I wanted to have a personal blog, and an easy way to add an 'engineering' blog to fledgling SaaS products, as well as release notes. The release notes now also serve to announce new features on my blog.

Status: Experimental. Works on my server ;-). 

Enjoy, [Willem van den Ende](https://willemvandenende.com)

## Project structure

This is a monorepo with two parts:

```
firehose/
├── app/                    # Phoenix application (OTP app: :firehose)
│   ├── lib/firehose/       # Application logic
│   ├── lib/firehose_web/   # Web layer (controllers, live views, components)
│   ├── lib/firehose/blogs/ # Blog definitions (engineering, release notes)
│   ├── priv/blog/          # Markdown posts
│   └── mix.exs
├── blogex/                 # Blogex library (multi-blog engine)
│   ├── lib/
│   └── mix.exs
└── mise.toml               # Runtime versions (Elixir, Erlang, Node)
```

Two blogs are configured:

| Blog | Route | Description |
|------|-------|-------------|
| Engineering | `/blog/engineering` | Main blog | 
| Release Notes | `/blog/releases` | What's new in an app |

## Prerequisites

- **Elixir** 1.15+ and **Erlang/OTP 26+** (managed by [mise](https://mise.jdx.dev))
- **Node.js** (managed by mise, for Tailwind + esbuild assets)
- **PostgreSQL** 16+ running on `localhost:5432`

## Setup

### 1. Install runtimes

```bash
mise install
```

This installs Elixir, Erlang, and Node at the versions specified in `mise.toml`.

### 2. Start PostgreSQL

You need PostgreSQL running locally with a `postgres` user (password: `postgres`).

**Option A — Docker (quick):**

```bash
docker run -d --name firehose-pg -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres -p 5432:5432 postgres:16
```

**Option B — Dev container:**

```bash
cd .devcontainer && docker compose up -d db
```

**Option C — System install:**

Install PostgreSQL normally and ensure a `postgres` user with password `postgres` exists.

### 3. Install dependencies and set up the database

```bash
cd app
mix setup
```

This runs:
- `mix deps.get` — fetch Hex and git dependencies
- `mix ecto.create` — create the `firehose_dev` database
- `mix ecto.migrate` — run database migrations
- `mix run priv/repo/seeds.exs` — seed initial data
- `mix assets.setup` — install Tailwind and esbuild
- `mix assets.build` — compile CSS and JS assets

### 4. Start the server

```bash
mix phx.server
```

Visit [localhost:8056](http://localhost:8056) in your browser.

> **Note:** The dev server runs on port `8056` by default. Override with `PORT=4000 mix phx.server`.

## Development commands

All commands below are run from the `app/` directory.

| Command | Description |
|---------|-------------|
| `mix phx.server` | Start the dev server with live reload |
| `iex -S mix` | Start an IEx session with the app |
| `mix test` | Run the test suite |
| `mix precommit` | Run all quality gates (compile, credo, format, test) |
| `mix format` | Format Elixir/HEEx code |
| `mix credo --strict` | Run Credo static analysis |

## Writing blog posts

Posts are markdown files with Elixir frontmatter. Place them under `app/priv/blog/<blog-name>/`:

```
app/priv/blog/
├── engineering/
│   └── 2026/
│       └── 05-01-hello-world.md
└── release-notes/
    └── 2026/
        └── 05-01-v0-1.md
```

Frontmatter format:

```markdown
%{
  title: "Hello World",
  author: "Willem van den Ende",
  tags: ~w(elixir phoenix blogex),
  description: "My first blog post"
}
---


This is my first post. It compiles into the BEAM at build time.
```

In dev mode, edited `.md` files trigger live reload automatically.

## Blogex

The [Blogex](./blogex/) library is a multi-blog engine for Phoenix apps, powered by [NimblePublisher](https://github.com/dashbitco/nimble_publisher). See [blogex/README.md](./blogex/README.md) for full documentation.

## License

MIT — see [LICENSE](./LICENSE)
