NTUST announcements in one place. bulletin polls the announcement boards of the university's
offices and departments, keeps every announcement for ten years (also after the school withdraws
it), and serves them at bulletin.ntust.org through a public API and a web frontend with search.
It is an unofficial service, not run by the university.
Status: the collector, rendering, the public API and the web frontend are built (specs under
openspec/specs/, history in docs/roadmap.md).
Contributors start with AGENTS.md.
Read-only JSON under https://bulletin.ntust.org/api/v1/, without authentication, open to any
origin. The OpenAPI document is /api/v1/openapi.json.
| Request | Answer |
|---|---|
GET /api/v1/announcements |
a page of the stream: {"items": [...], "next": cursor or null} |
GET /api/v1/announcements/{id} |
one announcement with its raw body, rendition, attachments and revisions |
GET /api/v1/events?after={id} |
events after an id, each with its announcement: {"events": [...], "last": id} |
GET /api/v1/sites |
the sites in the school's order, their unit's kind and college, and their boards |
GET /api/v1/tags |
the tag taxonomy with its labels |
GET /api/v1/files/{sha256}/{name} |
a stored copy of an attachment, while it is kept (one year) |
The stream lists announcements newest day first; copies of an announcement on other sites are folded into it. It takes these parameters, repeatable where marked:
| Parameter | Meaning |
|---|---|
site (repeatable) |
placed on a board of this site |
board (repeatable) |
placed on this board, <site>-<board> such as 1045-1391 |
tag (repeatable) |
carries this tag, <dimension>:<id> such as topic:scholarships; all must match |
from, to |
the stream day lies in this range, inclusive, YYYY-MM-DD |
q |
every word, matched as plain text, in the title or the text (at most 10 words) |
in=title |
search titles only |
cursor |
the next of the previous page |
limit |
items per page, 1 to 100, default 30 |
site and board together select one set of boards. Answers carry Cache-Control: public, max-age=60, stale-while-revalidate=600 and an ETag; send it back in If-None-Match for a 304.
Searches are limited to 30 a minute per client (429 with Retry-After); browsing is not limited.
Clients that follow the archive, such as a mirror, read /api/v1/events from the last id they
saw.
The Compose project bulletin (compose.yaml) runs two containers: bulletin-db, PostgreSQL 18
with PGroonga, and bulletin-internal, one process that serves the public listener (:8000), the
admin listener (bulletin-internal-admin:8001), the worker that polls the school and, with model
keys, the renderer that rewrites announcements. No ports are published; nginx-proxy-manager reaches
the public listener over the external network proxy-net.
- Create
proxy-netonce if the host does not have it:docker network create proxy-net. cp .env.example .env, then setPOSTGRES_PASSWORDandBULLETIN_ADMIN_TOKENS, andBULLETIN_MODEL_KEYSto render announcements.docker compose up -d --build. The first start applies the migrations and adds the boards ofseeds/boards.json; later starts add only boards the registry does not hold.docker compose psshowsbulletin-internalas healthy once/healthanswers.
In front of the public listener:
- Cloudflare proxies
bulletin.ntust.organd has a cache rule for/api/*that respects the origin's cache headers. - nginx-proxy-manager forwards
bulletin.ntust.orgtohttp://bulletin-internal:8000and puts Cloudflare'sCF-Connecting-IPlast inX-Forwarded-For, which the search limit counts by. Never forward to:8001.
To update, pull and run docker compose up -d --build again. docker compose down stops the
stack; the pgdata and files volumes keep the archive and the stored attachments.
| Variable | Default | Meaning |
|---|---|---|
POSTGRES_PASSWORD |
(required) | The database password, in hex, since it goes into a URL. |
BULLETIN_ADMIN_TOKENS |
none | Admin API tokens, comma-separated name:token pairs; tokens have 32 or more characters. |
BULLETIN_DATABASE_URL |
set by compose.yaml |
The PostgreSQL URL. |
BULLETIN_ADMIN_HOST |
set by compose.yaml |
The address the admin listener binds to. |
BULLETIN_FILES |
/data/files |
Where stored attachment files go. |
BULLETIN_SEED |
/app/seeds/boards.json |
The boards added on start. |
BULLETIN_MODEL_KEYS |
none | The model API's keys, comma-separated, used in turn; without any, nothing is rendered. |
BULLETIN_MODEL_FORMAT |
gemini |
gemini for Gemini's generateContent, openai for an OpenAI-compatible chat completions API. |
BULLETIN_MODEL_ENDPOINT |
https://generativelanguage.googleapis.com/v1beta |
The API's base URL. |
BULLETIN_MODEL |
gemini-4-hydrogen |
The model id. |
BULLETIN_MODEL_RATE |
10 |
Requests per key per minute. |
BULLETIN_THINKING_LEVEL |
low |
Gemini's thinking level, or reasoning_effort in the OpenAI format; empty sends none. |
BULLETIN_DISCORD_CHECK |
/app/tools/discord-markdown/check.mjs |
The Discord Markdown check that Node runs. |
BULLETIN_WEB |
/app/web |
The built frontend, served at /; without its index.html the page is off. |
The CLI works on the database directly. Boards are named <site>-<board>, such as 1053-1435.
docker compose exec app bulletin boards # every board: key, tier, category, name
docker compose exec app bulletin boards --tier P1
docker compose exec app bulletin boards --pending # discovered boards awaiting review
docker compose exec app bulletin tier set 1053-1435 P2 --by owner
docker compose exec app bulletin tier history 1053-1435
docker compose exec app bulletin review accept 1053-2000 --tier P4 --category announcement
docker compose exec app bulletin discover # queue a re-discovery of every siteA tier change takes effect at the next scheduling pass. A board turned on from off is queued
for backfill.
The admin listener answers only on the internal network bulletin_bulletin-admin, and every
request needs one of the bearer tokens; changes are recorded under the token's name.
| Request | Body | Answer |
|---|---|---|
GET /admin/boards?tier=P1&pending=true |
the boards, filters optional | |
GET /admin/boards/pending |
discovered boards awaiting review | |
PUT /admin/boards/{site}-{board}/tier |
{"tier": "P2"} |
204 |
GET /admin/boards/{site}-{board}/tier-changes |
the board's tier changes | |
POST /admin/boards/{site}-{board}/review |
{"tier": "P4", "category": "announcement"}, both optional |
204 |
docker run --rm --network bulletin_bulletin-admin curlimages/curl -s \
-H "Authorization: Bearer ${TOKEN}" "http://bulletin-internal-admin:8001/admin/boards?tier=P1"