# Icebase

Icebase is the anonymous crash, StrictMode, and freeze-reporting service for FrostWire Desktop and Android.

Storage is SQLite only. The PHP runtime must have the `SQLite3` extension (`php8.3-sqlite3` on Virginia). The database lives in the project-local `data/` directory. On Virginia, that project is on the EBS mount, so the database path is `/mnt/ebs/frostwire-files/frostwire-cloud/icebase.frostwire.com/data/icebase.sqlite3`. It is outside the Lighttpd document root, ignored by Git, protected by restrictive filesystem permissions, and included in a private backup plan. Icebase must refuse writes rather than silently fall back to the instance root volume if the EBS mount is unavailable.

## Privacy Boundary

Icebase must never receive or retain:

- Download URLs, magnet links, torrent names or hashes, search queries, filenames, peer or tracker data
- Application logs or arbitrary system properties
- IP addresses, User-Agent strings, device identifiers, advertising identifiers, usernames, or account data
- Persistent installation identifiers or any other identifying information

Reports use an explicit allowlist and a fresh per-report nonce only. Web-server and proxy configuration must prevent source IPs from being retained in access logs. Rate limiting may inspect an IP transiently, but must not persist it.

## Layout

- `skills/php-engineer/SKILL.md`: Icebase-specific PHP implementation guidance

## Admin Dashboard

The authenticated dashboard is available at `/admin.php`, separate from the anonymous ingestion endpoint. Configure `ICEBASE_ADMIN_PASSWORD_HASH` with the Base64-encoded output of PHP `password_hash()`; Base64 avoids PHP-FPM interpreting the hash's `$` characters. The dashboard accepts the Basic Auth username `admin`. Lifecycle changes are POST-only and require a session CSRF token.

## Virginia Lighttpd Deployment

The production configuration is maintained separately at:

`~/workspace/frostwire-tools/configs/lighttpd.confs/virginia1/lighttpd.conf`

The Icebase vhost fragment is maintained at:

`~/workspace/frostwire-tools/configs/lighttpd.confs/virginia1/conf-available/10-icebase.conf`

The Icebase vhost must be added explicitly for `icebase.frostwire.com` on TLS. It must:

- use the Icebase document root only
- route PHP through the existing PHP-FPM socket
- keep access logging disabled, or use a format that provably omits the source IP, User-Agent, URL query, and request body
- avoid `mod_extforward` for Icebase; the current global configuration trusts all forwarders and must not be used to derive a client identity
- enforce a small request-body limit and reject methods other than `POST` at the web-server boundary where supported
- avoid proxying Icebase through a component that retains source IPs or request payloads

Enable the fragment using the server's normal Lighttpd `conf-enabled` mechanism, validate the complete configuration, and reload only after the Icebase document root exists at `/var/www/icebase.frostwire.com/public`.

Public testing also requires DNS for `icebase.frostwire.com` to resolve to Virginia (`54.172.26.106`), either directly or through a CNAME to an existing Virginia hostname.

Before production activation, validate the complete rendered Lighttpd configuration, TLS certificate coverage, PHP-FPM connectivity, and logs using a synthetic report containing forbidden values. Confirm that no IP address, User-Agent, query string, or forbidden payload value appears in Lighttpd, PHP-FPM, syslog, or monitoring output.

Before starting Icebase, verify that `/mnt/ebs/frostwire-files` is a mounted filesystem with sufficient free space and that `/mnt/ebs/frostwire-files/frostwire-cloud/icebase.frostwire.com/data` has the expected owner and mode. Monitor free space and SQLite file growth; never place the database under `/var/www`, `/tmp`, or the instance root volume. The Lighttpd document root must be `/var/www/icebase.frostwire.com/public`; the EBS `data/` directory must not be a document root, alias, or symlink reachable from it.

## TLS Certificate

The existing FrostWire certificate is a wildcard certificate with:

- `DNS:*.frostwire.com`
- `DNS:frostwire.com`

Therefore it covers `icebase.frostwire.com`; a separate certificate name is not needed. The currently checked-out certificate is valid through `2026-10-11`. The existing renewal configuration uses Certbot with the Route53 DNS authenticator. After the next renewal, regenerate the Lighttpd merged PEM file, deploy the renewed certificate files, validate Lighttpd, and gracefully reload or restart Lighttpd according to the production procedure.