Skip to content
NTUST-OpenSourcePublic

About

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

bulletin

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.

Public API

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.

Deployment

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.

  1. Create proxy-net once if the host does not have it: docker network create proxy-net.
  2. cp .env.example .env, then set POSTGRES_PASSWORD and BULLETIN_ADMIN_TOKENS, and BULLETIN_MODEL_KEYS to render announcements.
  3. docker compose up -d --build. The first start applies the migrations and adds the boards of seeds/boards.json; later starts add only boards the registry does not hold.
  4. docker compose ps shows bulletin-internal as healthy once /health answers.

In front of the public listener:

  • Cloudflare proxies bulletin.ntust.org and has a cache rule for /api/* that respects the origin's cache headers.
  • nginx-proxy-manager forwards bulletin.ntust.org to http://bulletin-internal:8000 and puts Cloudflare's CF-Connecting-IP last in X-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.

Settings

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.

Operator commands

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 site

A tier change takes effect at the next scheduling pass. A board turned on from off is queued for backfill.

Admin API

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"

About

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages