CSS BHOP Map Index

A searchable Counter-Strike: Source bunnyhop map index with Steam login, Postgres-backed metadata, community ratings, screenshots, tags, and server-aware discovery features.

License

To the extent copyright is held in original SourceIndex source code and documentation, they are available under the GNU Affero General Public License, version 3 (AGPL-3.0-only). This notice does not assert copyright in material where none exists. The grant does not cover third-party dependencies, game assets, user uploads, or the tracked PNG/SVG/video files under public/; their provenance and permission to relicense are not yet established. See ops/public-release-audit.md before publishing a repository export.

Repo boundary note

The product can be checked out as site/ on a deployment host or as a standalone development worktree. Work from the repository root reported by Git, not an assumed path:

git rev-parse --show-toplevel
git status --short --branch

History rewrite

On 2026-10-08, the maintainers rewrote this repository's Git history to remove accidentally tracked private configuration and assistant-workspace files. The project commits, branches, pull requests, and issues remain in this Forgejo repository, but commit IDs from older clones no longer match. Re-clone the repository instead of merging an old local branch into the rewritten history. Pre-rewrite verified/* tags were invalidated; use only tags published by a successful current master workflow.

Features

• searchable and filterable map index
• random and ranked map browsing modes
• Steam-based authentication
• community ratings and difficulty voting
• tag taxonomy with moderation workflow
• screenshots and map asset management
• profile, leaderboard, and contribution tracking
• optional SourceJump-backed map and record integrations

Tech stack

• Node.js
• Express
• PostgreSQL
• vanilla JS modules on the frontend

Project layout

• server/ application server, auth, DB access, schema, integrations
• public/ static pages, frontend modules, assets
• test/ regression tests
• e2e/ isolated Chromium journeys
• ops/ release and operational contracts
• ARCHITECTURE.md system overview
• CONTRIBUTING.md contributor guidance

Local setup

Install dependencies:

npm ci --include=dev

Copy env template and adjust values for your environment:

cp .env.example .env

Important before publishing or deploying:

• keep real secrets only in uncommitted .env files or your deployment secret manager
• docker-compose.yml is now secret-free and reads runtime config from .env
• review ALLOW_DEV_AUTH, SESSION_SECRET, DATABASE_URL, STEAM_API_KEY, and all admin credentials before going public

Initialize the database schema:

npm run db:init

Start the app:

npm start

Default local port is 3000 unless overridden.

Testing

Run the full test suite:

npm test

Optional checks:

npm run typecheck
npm run deploy:smoke

If npm run typecheck fails because node_modules/typescript is missing, refresh dependencies with npm ci and verify the lockfile and install state match before treating it as an app regression.

Key environment variables

Common settings are documented in .env.example.

Important ones include:

• DATABASE_URL
• POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB
• SESSION_SECRET
• STEAM_REALM
• STEAM_RETURN_URL
• STEAM_API_KEY
• ALLOW_DEV_AUTH
• COOKIE_SECURE
• SourceJump and records-provider settings
• conservative SourceJump mirror settings (SOURCEJUMP_MIRROR_*): one queued map/minute, one incomplete record detail/5 seconds, and one duplicate-bounded latest-record walk/hour
• slow-probe credentials/files via the root .env plus scripts/source-server-probe/.env for local probe tooling

Security notes

Minimum safe production expectations:

• ALLOW_DEV_AUTH=false
• COOKIE_SECURE=true
• SESSION_SECRET should be long and random
• use a non-default database password
• never commit filled .env, probe credentials, generated tickets, local storage, or coverage artifacts

The app also enforces additional production auth checks in code.

Operations notes

The app uses in-memory caches and background prewarm/refresh loops for hot routes such as /api/maps and /api/servers. Map contributor suggestions and Steam-ID lookups use indexed per-person rows in map_contributors; existing map writes synchronize them transactionally while legacy fields remain available for compatibility. The normalization audit is in ops/data-normalization-audit.md. Long-lived metadata caches use bounded LRU eviction so arbitrary query, profile, map, and viewer keys cannot grow process memory without limit. Their capacities are configurable through the *_CACHE_MAX_ENTRIES settings in .env.example; current entry and eviction counts are visible in the Admin runtime-performance panel. Cache invalidation is generation-aware, so a request that started before a map mutation cannot restore stale list or detail data after the mutation completes.

At startup, frontend source is copied into .runtime/public-releases/<content-hash>, all local JS/CSS references are rewritten to immutable /_assets/<content-hash>/... URLs, and the current symlink is replaced atomically only after the complete tree is ready. Source imports use the stable ?v=source marker; manual cache-token bumps are no longer required.

For more detail, see ARCHITECTURE.md.

Contributing

See CONTRIBUTING.md for project conventions and safe refactor guidance.