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 (
.bxmtemplates) and the built admin from one process. - Database: MySQL 8, with numbered migrations in
server/migrationsapplied 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 inApi.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_HEADERto the header your proxy puts the visitor's address in (X-Real-IP, orCF-Connecting-IPbehind 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
./backupsevery 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.