Dev Mode Quick Start
make generate regenerates both templ output and
internal/web/static/css/generated_geometry.css. The geometry stylesheet is a
finite set of CSP-safe positioning classes used by mail gestures, context menus
and calendar events; edit scripts/gen-geometry when its ranges or increments
need to change, never the generated CSS directly.
The application assets intentionally need no bundler. Templates load CSS in
this cascade order: bongo.css (tokens and shell), bongo-mail.css,
bongo-apps.css, bongo-utilities.css, then bongo-components.css (canonical
shared component states). JavaScript loads bongo.js (core),
bongo-components.js (Alpine registrations), bongo-mail.js (mail and keyboard
interactions), then bongo-pages.js (page lifecycle hooks). Keep those orders
when adding a test fixture or layout.
Build and Run
make dev
make dev generates the templates, builds bin/bongo and bin/bongo-import,
starts a dev server, runs the validation suite, seeds test data
and keeps the server running until Ctrl-C. The web UI is at
http://localhost:8080.
To run the server by hand:
make build
./bin/bongo serve --dev
Dev mode starts a single-node server with ephemeral storage (deleted on shutdown) and needs no configuration. The web UI is always plain HTTP in dev mode; the IMAPS and POP3S ports use a self-signed certificate.
Static assets are cache-busted by commit hash. After rebuilding from a new commit, reload open tabs to pick up changed JavaScript and CSS.
Default Ports
| Service | Port | Protocol |
|---|---|---|
| HTTP | 8080 | Web UI, health |
| Control | 8081 | /internal, loopback only |
| SMTP MX | 2525 | Inbound mail |
| SMTP Sub | 2587 | Submission (auth) |
| SMTPS Sub | 2465 | Submission, implicit TLS |
| IMAP | 1143 | Plaintext/STARTTLS |
| IMAPS | 1993 | Implicit TLS |
| POP3 | 1110 | Plaintext/STARTTLS |
| POP3S | 1995 | Implicit TLS |
Test User
Dev mode creates a test user on startup:
- Email:
admin@localhost - Password:
admin
Test Data
make dev seeds already. Against a dev server started by hand:
make seed
The seed creates the users alice, bob and charlie (@localhost),
messages, subfolders, contacts and calendar events. Running it twice creates
duplicate contacts and events.
Send a Test Email
Using swaks:
swaks --to admin@localhost \
--from sender@example.com \
--server 127.0.0.1:2525 \
--header "Subject: Hello from swaks" \
--body "This is a test message."
Or with Go’s net/smtp, saved as send.go and run with go run send.go:
package main
import "net/smtp"
func main() {
smtp.SendMail("127.0.0.1:2525", nil, "sender@example.com",
[]string{"admin@localhost"}, []byte("Subject: Test\r\n\r\nHello"))
}
Connect Thunderbird
- Open Thunderbird, go to Account Settings > Account Actions > Add Mail Account.
- Enter:
- Name:
Admin - Email:
admin@localhost - Password:
admin
- Name:
- Click Configure manually and set:
- Incoming (IMAP):
- Server:
127.0.0.1 - Port:
1143 - SSL: None
- Authentication: Normal password
- Server:
- Outgoing (SMTP):
- Server:
127.0.0.1 - Port:
2587 - SSL: None
- Authentication: Normal password
- Server:
- Incoming (IMAP):
- Click Done (accept any certificate warnings for self-signed certs).
Screenshot Every Route
make ui-shots builds the server into a temporary directory, starts a dev
server on free ports, seeds it, logs in and captures each main route at
desktop, phone and tablet sizes in light and dark modes with headless Chrome.
Focused inbox captures also exercise 200% zoom, forced colours and reduced
motion, while an automated audit reports duplicate IDs, unnamed controls,
horizontal overflow, console errors, CSP violations and failed same-origin
requests. Captures are full-page and include the open mobile navigation drawer.
make ui-shots # screenshots go to a new temp dir
make ui-shots OUT=~/shots # OUT must be outside the repository
go run ./scripts/ui-shots -out ~/shots -timeout 30s -chrome /path/to/chrome
It needs a local Chrome or Chromium and never downloads one. Exit status is 0
when every capture is clean, 1 when a route has errors, and 2 when setup
failed; through make any failure shows as make’s exit status 2, so read the
output. It is not run in CI.
Verify
Check the health endpoint:
curl http://127.0.0.1:8080/health/ready
Returns {"status":"ready"} when the server is fully initialised.