Journal

Journal is a simple, self-hosted web-based journal written in Go. You can create, edit and view entries in Markdown format, with a clean web interface and a full REST API. All data is stored in a SQLite database — no database server required, just a single file on disk.

I built it for personal use and continue to use it every day for my own journalling. It's also designed to be a good learning project for developers who are getting started with Go — it deliberately has only two dependencies so the full end-to-end flow can be understood through standard Go libraries.

The latest release is v1.0. Read the blog post about what changed in v1.0, or head to the GitHub repository to explore the source code, open issues, or contribute.

Features

  • Create, edit and view journal entries written in Markdown
  • Calendar view for browsing entries by month and year
  • Random article endpoint to surface older entries
  • Stats page showing entry counts, word counts and visit data
  • REST API with an OpenAPI 3.0 specification
  • Visit and request tracking stored in the database
  • Themeable front-end with a clean default theme
  • Configurable entirely through environment variables
  • Optional SSL/TLS support and secure session handling

Installation

Homebrew (macOS)

brew tap jamiefdhurst/journal
brew install journal

Docker

docker run -d \
  --name journal \
  -p 3000:3000 \
  -v /var/lib/journal:/go/data \
  jamiefdhurst/journal:latest

Images are also published to the GitHub Container Registry as ghcr.io/jamiefdhurst/journal:latest.

Debian / Ubuntu (apt)

curl -fsSL https://jamiefdhurst.github.io/packages/journal.asc \
  | sudo tee /usr/share/keyrings/journal.asc > /dev/null

echo "deb [signed-by=/usr/share/keyrings/journal.asc] \
  https://jamiefdhurst.github.io/packages stable main" \
  | sudo tee /etc/apt/sources.list.d/journal.list

sudo apt update && sudo apt install journal

CentOS / RHEL / Fedora (yum/dnf)

sudo tee /etc/yum.repos.d/journal.repo > /dev/null <<'EOF'
[journal]
name=Journal
baseurl=https://jamiefdhurst.github.io/packages/yum
enabled=1
gpgcheck=1
gpgkey=https://jamiefdhurst.github.io/packages/journal.asc
EOF

sudo yum install journal

Build from source

git clone https://github.com/jamiefdhurst/journal.git
cd journal
go mod download
go build -o journal ./cmd/journal
./journal

Pre-built ZIP archives for Linux and macOS (amd64 and arm64) are attached to every GitHub release.

Configuration

Journal is configured through environment variables, or optionally a .env file.

  • J_TITLE — title of your journal
  • J_DESCRIPTION — HTML description
  • J_PORT — port to serve on, default 3000
  • J_DB_PATH — path to the SQLite database, default ./data/journal.db
  • J_CREATE — set to 0 to disable entry creation
  • J_EDIT — set to 0 to disable editing
  • J_THEME — theme to use from the web/themes folder, default default
  • J_POSTS_PER_PAGE — entries per page, default 20
  • J_EXCERPT_WORDS — preview length on the index, default 50
  • J_SSL_CERT / J_SSL_KEY — paths to certificate and key for HTTPS
  • J_SESSION_KEY — 32-character AES-256 key for session encryption

Full configuration reference and a reverse proxy setup guide are available in the installation guide.

API

Journal exposes a REST API documented with an OpenAPI 3.0 specification. The spec is available at /openapi.yml on any running instance, and the API documentation covers all available endpoints including entries, stats, and the random article endpoint.

Source and Contributing

The full source code is available on GitHub. Issues and pull requests are welcome — whether that's a bug report, a feature idea, or an improvement to the documentation. The project follows conventional commits for versioning, and there's a commit convention guide in the repository.