Clear community instance (operator guide)

Glassy Clear is a community membership — a private community that lives inside Glassy, with early access to new tools, a downloads store, roadmap input, and Glassy Self-Host. For what the membership includes, see the Clear page.

This page is the operator runbook for running the Clear community instance — the private, Clear-mode deployment that hosts the membership. It is not a "self-hosted tier" that end users buy; members get their own single-user Docker build separately (see Self-hosting Glassy).

The full operator runbook lives in the application repo at deploy/clear/README.md.

Image variants (v2.55.0+)

Clear's community service uses the hosted build. It is not the single-user appliance, even when operated on your own infrastructure. Hosted floating tags are :main and :latest; appliance releases use versioned tags such as v2.53.0. The :selfhost-main tag is a moving appliance build for testers, not a reproducible release pin.

The appliance-only UI is compiled into its image. Setting runtime feature flags on a hosted image cannot restore code omitted at build time. Use the installer and its versioned pin for a personal appliance; see Self-hosting Glassy.

What the Clear community instance is

The Clear community instance is the same Glassy application binary, configured at deploy time with INSTANCE_ID=clear. At that point:

• Pro upsells are hidden. The Pro pricing card, AI upgrade modal, Public Window upsell, Pro-only checkout flows, FAQ pricing rows, and landing-page Pro teaser all branch on isClearInstance() and either hide or redirect.
• Clear membership plans remain available. Glassy Clear ($80/mo or $300/yr) continues to be purchasable. GlassyCalc is a plain feature of every account now, not a sidecar for sale.
• pro_* plans are server-rejected. The commerce checkout endpoint returns 400 Pro plans are not available on this instance if a pro_* plan is requested on a Clear instance, even if a stale client tries.
• The public app.glassy.fyi instance is unaffected — Clear gating is opt-in via the INSTANCE_ID env var; default deployments behave exactly as before.

What you need

• A host with Docker and Docker Compose (Linux recommended).
• A Stripe account with the Clear monthly + yearly prices (and optionally clear_lifetime if you want to grandfather an existing cohort).
• A domain pointed at your host. TLS via your usual reverse proxy (Caddy / Cloudflare / nginx).

Cloud vs self-hosted: what works where

Some features require the Glassy server to reach services on your machine (127.0.0.1). A cloud-hosted server cannot do this. Self-hosting on your own machine is required for:

Capability	Cloud (app.glassy.fyi)	Self-hosted (this)
Notes, AI, capture, companion	Yes	Yes
Live Obsidian vault sync	No (server cannot reach your localhost)	Yes
Ollama local AI	No	Yes
Data location	Cloud VM	Your machine

For a neutral self-host recipe (not Clear-specific), see deploy/selfhost/docker-compose.yml in the application repo.

Security recommendations

For any self-hosted deployment, we recommend: - SSH: Disable root login and password authentication. Use key-based auth only. - Firewall: Enable UFW or equivalent, allowing only ports you actively use (e.g., 22, 80, 443, 3000). - Fail2ban: Install and enable fail2ban with the sshd jail for brute-force protection. - File permissions: Ensure .env.production and your SQLite database are 600 (owner read/write only). - Updates: Enable unattended-upgrades for automatic security patches.

Quick start

# Note: The 0Reliance/glassy repo is private during beta. Request access first.
git clone https://github.com/0Reliance/glassy.git
cd glassy/deploy/clear
cp .env.example .env
# Edit .env — set INSTANCE_ID=clear, INSTANCE_ACCESS_MODE_DEFAULT,
# Stripe keys, JWT secret, allowed origins, etc.
docker compose up -d

The Compose file launches the app with INSTANCE_ID=clear baked in. On first boot the database is migrated automatically.

Scripting this, or handing it to an AI agent?

A fresh install refuses every authenticated /api/* call with 403 PASSWORD_CHANGE_REQUIRED until the seeded owner's password is changed — but POST /api/auth/login is not behind that wall, so a script logs in, gets a valid token, and then 403s on everything else. That is not a broken install. See Self-hosting → If you are scripting the install for the three-call sequence and the two different meanings of 403.

Key environment variables

Variable	Effect
INSTANCE_ID=clear	Activates the Clear gating SSOT (isClearInstance() returns true).
INSTANCE_ACCESS_MODE_DEFAULT=private	Optional. Hides the entire site from logged-out visitors; deep-links resume after sign-in. See Private Instance Mode.
STRIPE_SECRET_KEY / STRIPE_PUBLISHABLE_KEY	Stripe live keys for your Clear instance.
ENABLE_CLEAR_LIFETIME / VITE_ENABLE_CLEAR_LIFETIME	Off by default. Only enable if you are migrating a grandfathered Clear Lifetime cohort. New Clear Lifetime sales are not offered on the public instance.

The full list of environment variables is in deploy/clear/.env.example.

Public + private modes

A Clear instance can be combined with instance-wide private mode (see Private instance mode — runbook at docs/private-instance-mode.md in the application repo). Any combination is supported:

Visibility	Registration	Use case
Public	Open	Public Clear instance with self-serve signup
Public	Closed	Public Clear instance with admin-issued invitations
Private	Open	Members-only site with public registration form
Private	Closed	Fully closed Clear instance — admin invites only

Stripe configuration

Clear instances resolve priceId from the Stripe catalog by lookup key at boot. Provision these lookup keys in Stripe (Dashboard → Products → Prices → Edit price → "Lookup key"):

• clear_monthly
• clear_yearly
• (optional, only if grandfathering) clear_lifetime
• ai_topup_10 / ai_topup_20 / ai_topup_50 (one-time AI credit packs)

You do not need any pro_* lookup keys on a Clear instance — those routes are gated server-side.

Upgrading

The Clear community instance follows the public Glassy release cadence. To upgrade:

cd glassy/deploy/clear
git pull
docker compose pull
docker compose up -d

Database migrations run automatically on container start.

Pointers

• Application repo: https://github.com/0Reliance/glassy
• Operator runbook: deploy/clear/README.md
• Clear pricing & policy: see the in-app Settings → Billing screen on a Clear instance.
• Pricing source of truth: Pro $17/mo or $100/yr · Clear $80/mo or $300/yr · AI top-ups $10/$20/$50 → 100k/200k/500k credits, never expire.