Project

BoxPress

An open-source blogging platform on BoxLang and boxlang-express, and a complete, working app to install and make your own. Readers get fast, server-rendered pages. Writers get a composer with visual and Markdown editing that never loses a draft. Admins get the site's traffic and the running server's health in the same place. It's one process and one MySQL database, with nothing hosted elsewhere and no third-party analytics.

A composer for writers

Visual editing (Tiptap) or plain Markdown (CodeMirror), with a preview the server renders. Paste or drop images to upload them. Unsaved work is kept in the browser and sent to the server every minute, and every save is kept as a revision.

Built to be changed

One class per area of the API, one service per concern, numbered SQL migrations applied at startup, and a spec suite that builds the whole app. Open any file and follow what it does.

Insights without a tracker

Page views, top posts, referrers, searches and broken links from the site's own access log, with bots flagged and no IP addresses stored. Server memory, CPU, garbage collection, per-route timings and the database pool, charted over 90 days.

Safe by default

Post bodies are rendered from Markdown when saved and sanitized, so an author's account can't put script on the site. Password and passkey sign-in with rate limits, and in production an admin's powers need a session confirmed with a passkey.

What's in it

  • Writing: a visual or Markdown editor with a live preview, tags, cover images (cropped to the shape the site shows them in), excerpts, custom addresses, and scheduled posts that go live on their own at their time.
  • History: the latest 30 saves of every post, plus the editor's unsaved work, so a draft can be picked up on another device.
  • Media library: uploads lose their location and camera details on the way in, can be resized and converted to WebP in the browser first, and carry alt text that's filled in when an image is inserted. Files go on local disk or in any S3-compatible bucket (R2, S3, MinIO, B2).
  • The site: a quiet, reading-first design with self-hosted fonts and one accent colour from Admin › Settings. Tag, author and search pages, an RSS feed, sitemap.xml, robots.txt, Open Graph and Twitter cards, and light and dark modes.
  • People: admins manage everything; authors write and manage their own posts.

Stack

  • Server: BoxLang 1.18+ with boxlang-express, serving the JSON API, the public pages (.bxm templates) and the built admin from one process.
  • Database: MySQL 8, with numbered migrations in server/migrations applied at startup.
  • Admin: React 19, MUI, TanStack Router and Query, Tiptap and CodeMirror, built with Vite.

How it's put together

server/routes/Api.bx builds the app, and each area of the API is a class with a static register() that takes the router and the services it needs. This is the whole tags API:

boxlangclass {

	static void function register( required router, required struct svc ) {
		var tags = arguments.svc.tags

		arguments.router.get( "/tags", ( req, res ) => res.json( tags.all() ) )

		arguments.router.patch( "/tags/:id", ( req, res ) => {
			if ( !req.user.isAdmin ) {
				ApiError::forbidden()
			}
			res.json( tags.rename( Http::pathId( req.params ), Http::requiredString( Http::body( req ), "name", 50 ) ) )
		} )
	}

}

Closures don't inherit the enclosing function's arguments scope, so anything a handler needs is copied into a local variable first. server/services/Bootstrap.bx loads the settings and wires the services: Posts, Revisions, Media, Sanitizer, Insights, ServerMonitor and the rest. Background work uses app.schedule(): flushing the request log, summarizing each finished day for Insights, pruning sessions and recording server history.

Some ways to make it your own:

  • Change the public templates in server/views/site/.
  • Add a route class next to the others in server/routes/ and register it in Api.bx.
  • Add a numbered migration and a service for a new feature.
  • Add a section to the admin under web/src/admin/modules/.

Running it locally

You need BoxLang 1.18+, Node 20.19+ (or 22), MySQL 8, and CommandBox for the tests. Create boxpress_development and boxpress_test databases with the utf8mb4 character set, then:

bashinstall-bx-module boxlang-express bx-mysql bx-password-encrypt bx-markdown bx-esapi bx-passkeys
cp server/.env.example server/.env   # then set BOXPRESS_DB_PASSWORD
cd web && npm install && npm run build && cd ..
server/start.sh

The site is at http://localhost:8080 and the admin at /admin. A new site has one account, admin with the password admin; change it under Account, or set BOXPRESS_ADMIN_* in .env before the first start to begin with your own. For hot reload while working on the admin, run npm run dev in web/ as well.

Production with Docker

docker-compose.yml runs the app, MySQL 8.4 and a nightly database backup:

bashcp .env.example .env   # set SITE_URL, MYSQL_PASSWORD and MYSQL_ROOT_PASSWORD
docker compose up -d --build
  • The default admin account can't sign in in production until it has a password of its own: docker compose exec app boxlang scripts/users.bxs password admin.
  • The app listens on 127.0.0.1:8080. Put a reverse proxy that terminates HTTPS in front of it, such as Caddy or nginx.
  • Set TRUST_PROXY_HEADER to the header your proxy puts the visitor's address in (X-Real-IP, or CF-Connecting-IP behind Cloudflare), so the sign-in and search limits count real visitors instead of the proxy.
  • Passkeys belong to the domain in SITE_URL, so changing the domain later leaves every one behind.
  • Backups go to ./backups every night and are kept for 14 days. They're on the same disk as the database, so copy them elsewhere too.

Tests

The specs build the whole app against the boxpress_test database and empty it before each one: signing in and CSRF, roles, posts and scheduling, sanitizing, revisions, search, feeds, uploads, settings, accounts and server metrics.

bashcd server && box install && boxlang run-tests.bxs

Licence

MIT.