diff --git a/VERSION b/VERSION index 54d1a4f..a803cc2 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.13.0 +0.14.0 diff --git a/backend/alembic/versions/0025_install_wizard.py b/backend/alembic/versions/0025_install_wizard.py new file mode 100644 index 0000000..a3026d8 --- /dev/null +++ b/backend/alembic/versions/0025_install_wizard.py @@ -0,0 +1,39 @@ +"""first-run install wizard state + +Revision ID: 0025_install_wizard +Revises: 0024_google_email_verified +Create Date: 2026-06-19 + +Adds app_state.configured + setup_token_hash for the first-run install wizard. Existing installs +(any users present) are marked configured so they never see the wizard; a genuinely fresh DB (no +users) starts unconfigured and boots into setup mode. +""" +from typing import Sequence, Union + +import sqlalchemy as sa +from alembic import op + +revision: str = "0025_install_wizard" +down_revision: Union[str, None] = "0024_google_email_verified" +branch_labels: Union[str, Sequence[str], None] = None +depends_on: Union[str, Sequence[str], None] = None + + +def upgrade() -> None: + op.add_column( + "app_state", + sa.Column("configured", sa.Boolean(), nullable=False, server_default="false"), + ) + op.add_column("app_state", sa.Column("setup_token_hash", sa.String(length=64), nullable=True)) + # Ensure the singleton row exists and mark it configured, then revert to unconfigured only if + # this is a genuinely fresh DB (no users yet). Net: configured = (the instance already has users). + op.execute( + "INSERT INTO app_state (id, sync_paused, configured) VALUES (1, false, true) " + "ON CONFLICT (id) DO UPDATE SET configured = true" + ) + op.execute("UPDATE app_state SET configured = false WHERE NOT EXISTS (SELECT 1 FROM users)") + + +def downgrade() -> None: + op.drop_column("app_state", "setup_token_hash") + op.drop_column("app_state", "configured") diff --git a/backend/app/auth.py b/backend/app/auth.py index e3fc79a..88f4549 100644 --- a/backend/app/auth.py +++ b/backend/app/auth.py @@ -75,14 +75,40 @@ log = logging.getLogger("subfeed.auth") router = APIRouter(prefix="/auth", tags=["auth"]) -oauth = OAuth() -oauth.register( - name="google", - client_id=settings.google_client_id, - client_secret=settings.google_client_secret, - server_metadata_url="https://accounts.google.com/.well-known/openid-configuration", - client_kwargs={"scope": BASE_SCOPES}, -) +# The Google OAuth client is built lazily from the CURRENT credentials (DB override via sysconfig, +# else env), so the install wizard / admin can set or change them at runtime without a restart. The +# authlib registry is rebuilt only when the creds change (cheap, first use after a change). +_oauth = OAuth() +_oauth_creds: tuple[str, str] | None = None + + +def google_oauth(db: Session): + """The configured authlib Google client, or None when no credentials are set (Google sign-in + is then disabled — email+password still works).""" + global _oauth, _oauth_creds + cid = sysconfig.get_str(db, "google_client_id") + csec = sysconfig.get_str(db, "google_client_secret") + if not cid or not csec: + return None + if _oauth_creds != (cid, csec): + _oauth = OAuth() + _oauth.register( + name="google", + client_id=cid, + client_secret=csec, + server_metadata_url="https://accounts.google.com/.well-known/openid-configuration", + client_kwargs={"scope": BASE_SCOPES}, + ) + _oauth_creds = (cid, csec) + return _oauth.google + + +def google_enabled(db: Session) -> bool: + """Whether Sign in with Google is available (both client id + secret resolve to non-empty).""" + return bool( + sysconfig.get_str(db, "google_client_id") + and sysconfig.get_str(db, "google_client_secret") + ) def has_read_scope(user: User) -> bool: @@ -178,11 +204,16 @@ def upsert_pending_invite(db: Session, email: str) -> Invite | None: @router.get("/login") -async def login(request: Request): +async def login(request: Request, db: Session = Depends(get_db)): # access_type=offline ensures a refresh_token on first authorization. We avoid # prompt=consent so returning users get a quick sign-in; the stored refresh token # is kept when Google doesn't re-issue one (see the callback). - return await oauth.google.authorize_redirect( + client = google_oauth(db) + if client is None: + # Google sign-in isn't configured on this instance — land back on the login page (the UI + # hides the button, so this is just a safety net for a stale/direct hit). + return RedirectResponse(url="/") + return await client.authorize_redirect( request, settings.oauth_redirect_url, access_type="offline", @@ -198,8 +229,11 @@ async def callback( background: BackgroundTasks, db: Session = Depends(get_db), ): + client = google_oauth(db) + if client is None: + return RedirectResponse(url="/") try: - token = await oauth.google.authorize_access_token(request) + token = await client.authorize_access_token(request) except OAuthError as exc: raise HTTPException(status_code=400, detail=f"OAuth error: {exc.error}") @@ -661,15 +695,22 @@ def require_human(user: User = Depends(current_user)) -> User: @router.get("/link") -async def link_google(request: Request, user: User = Depends(current_user)): +async def link_google( + request: Request, + user: User = Depends(current_user), + db: Session = Depends(get_db), +): """Start linking a Google account to the signed-in (e.g. password) account. Requests only the identity scopes — YouTube access is granted separately via /auth/upgrade. The callback sees `oauth_link_uid` and attaches the identity instead of creating a new account.""" if user.is_demo: return RedirectResponse(url="/") + client = google_oauth(db) + if client is None: + return RedirectResponse(url="/?link=error") request.session["oauth_link_uid"] = user.id request.session["oauth_link_explicit"] = True - return await oauth.google.authorize_redirect( + return await client.authorize_redirect( request, settings.oauth_redirect_url, access_type="offline", @@ -705,7 +746,10 @@ def set_password( @router.get("/upgrade") async def upgrade( - request: Request, access: str = "read", user: User = Depends(current_user) + request: Request, + access: str = "read", + user: User = Depends(current_user), + db: Session = Depends(get_db), ): """Incremental consent for the onboarding wizard. `access=read` grants YouTube read-only (enough to build the feed); `access=write` additionally grants management @@ -716,11 +760,14 @@ async def upgrade( # straight home (no YouTube link is ever attached to it) rather than shown a raw 403. if user.is_demo: return RedirectResponse(url="/") + client = google_oauth(db) + if client is None: + return RedirectResponse(url="/") # Attach the grant to THIS account in the callback. Without it a password account (no # google_sub) would get a brand-new, separate Google user created instead of being linked. request.session["oauth_link_uid"] = user.id scope = WRITE_SCOPES if access == "write" else READ_SCOPES - return await oauth.google.authorize_redirect( + return await client.authorize_redirect( request, settings.oauth_redirect_url, access_type="offline", @@ -739,3 +786,13 @@ async def me(user: User = Depends(current_user)) -> dict: "avatar_url": user.avatar_url, "role": user.role, } + + +@router.get("/config") +def auth_config(db: Session = Depends(get_db)) -> dict: + """Public: which sign-in options this instance offers, so the login page can hide what's off + (e.g. no Google button when Google OAuth isn't configured).""" + return { + "google_enabled": google_enabled(db), + "allow_registration": sysconfig.get_bool(db, "allow_registration"), + } diff --git a/backend/app/main.py b/backend/app/main.py index 220b1a5..d000c16 100644 --- a/backend/app/main.py +++ b/backend/app/main.py @@ -20,12 +20,13 @@ if not _subfeed_logger.handlers: log = logging.getLogger("subfeed.app") from fastapi.middleware.cors import CORSMiddleware -from fastapi.responses import FileResponse +from fastapi.responses import FileResponse, JSONResponse from fastapi.staticfiles import StaticFiles from starlette.middleware.sessions import SessionMiddleware -from app import auth +from app import auth, state from app.config import settings +from app.db import SessionLocal from app.routes import ( admin, channels, @@ -37,6 +38,7 @@ from app.routes import ( playlists, quota, scheduler as scheduler_routes, + setup as setup_routes, sync, tags, version, @@ -47,6 +49,17 @@ from app.scheduler import shutdown_scheduler, start_scheduler @asynccontextmanager async def lifespan(app: FastAPI): log.info("Siftlode starting up") + # First-run: if the instance isn't configured yet, mint a fresh one-time setup token and print + # the wizard URL so the operator can open it (the app runs in setup mode until they finish). + with SessionLocal() as db: + if not state.is_configured(db): + token = state.rotate_setup_token(db) + url = f"{settings.app_base}/setup?token={token}" + log.warning( + "FIRST-RUN SETUP REQUIRED — this instance isn't configured yet.\n" + " Open the install wizard (internal access only):\n %s", + url, + ) start_scheduler() try: yield @@ -73,6 +86,27 @@ if settings.frontend_origin: allow_headers=["*"], ) +# Paths reachable while the instance is unconfigured (setup mode). Everything else under /api or +# /auth is locked until the wizard finishes; static/SPA always loads so the wizard page can render. +_SETUP_OPEN_PREFIXES = ("/api/setup", "/api/version") + + +@app.middleware("http") +async def setup_gate(request, call_next): + """Lock the app to the install wizard until it's configured. Skips the DB entirely once setup + completed in this process (the cached fast-path), so there's no steady-state overhead.""" + if not state.setup_complete(): + path = request.url.path + if path.startswith(("/api/", "/auth/")) and not path.startswith(_SETUP_OPEN_PREFIXES): + with SessionLocal() as db: + configured = state.is_configured_cached(db) + if not configured: + return JSONResponse( + {"detail": "This instance isn't set up yet."}, status_code=503 + ) + return await call_next(request) + + app.include_router(health.router) app.include_router(auth.router) app.include_router(sync.router) @@ -87,6 +121,7 @@ app.include_router(config_routes.router) app.include_router(scheduler_routes.router) app.include_router(quota.router) app.include_router(version.router) +app.include_router(setup_routes.router) # The built SPA (populated by the Docker frontend build stage). STATIC_DIR = Path(__file__).parent / "static_spa" diff --git a/backend/app/models.py b/backend/app/models.py index 388ba36..623da7b 100644 --- a/backend/app/models.py +++ b/backend/app/models.py @@ -383,6 +383,14 @@ class AppState(Base): # Admin override for the maintenance job's rolling re-validation batch (videos re-checked # per run). NULL = use the config/env default (settings.maintenance_revalidate_batch). maintenance_revalidate_batch: Mapped[int | None] = mapped_column(Integer) + # First-run install wizard. `configured` is False on a fresh instance (the app runs in + # setup mode: only the wizard works) and flipped True when the wizard finishes. While + # unconfigured, a one-time setup token (only its SHA-256 hash stored) gates the wizard; + # the raw token + URL are printed to the container logs on each startup. + configured: Mapped[bool] = mapped_column( + Boolean, default=False, server_default="false" + ) + setup_token_hash: Mapped[str | None] = mapped_column(String(64)) class SchedulerSetting(Base): diff --git a/backend/app/routes/me.py b/backend/app/routes/me.py index 6d05883..26498b4 100644 --- a/backend/app/routes/me.py +++ b/backend/app/routes/me.py @@ -2,7 +2,14 @@ from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException, Request from sqlalchemy import func, select from sqlalchemy.orm import Session -from app.auth import current_user, has_read_scope, has_write_scope, is_allowed, purge_user +from app.auth import ( + current_user, + google_enabled, + has_read_scope, + has_write_scope, + is_allowed, + purge_user, +) from app.db import get_db from app.models import Invite, User @@ -80,6 +87,9 @@ def get_me( "is_demo": user.is_demo, "has_google": user.google_sub is not None, "has_password": user.password_hash is not None, + # Instance-wide: whether Google sign-in / YouTube connect is available at all (the UI hides + # YouTube-access affordances and the onboarding nudge when it isn't configured). + "google_enabled": google_enabled(db), "can_read": has_read_scope(user), "can_write": has_write_scope(user), "pending_invites": pending_invites, diff --git a/backend/app/routes/setup.py b/backend/app/routes/setup.py new file mode 100644 index 0000000..bea3542 --- /dev/null +++ b/backend/app/routes/setup.py @@ -0,0 +1,109 @@ +"""First-run install wizard. + +`GET /api/setup/status` is public (the SPA uses it to decide whether to show the wizard). Every +mutating step goes through `require_setup`: it rejects once the instance is configured AND requires +the one-time setup token (printed to the container logs at first boot, carried by the wizard as the +X-Setup-Token header). The wizard steps themselves are added in epic 6c. +""" +from fastapi import APIRouter, Depends, Header, HTTPException +from sqlalchemy import select +from sqlalchemy.orm import Session + +from app import email as email_mod +from app import state, sysconfig +from app.auth import PASSWORD_MIN_LEN +from app.db import get_db +from app.models import User +from app.security import hash_password + +router = APIRouter(prefix="/api/setup", tags=["setup"]) + + +def require_setup( + x_setup_token: str | None = Header(default=None), + db: Session = Depends(get_db), +) -> Session: + """Gate for setup steps. Returns the db session for the handler to reuse.""" + if state.is_configured(db): + raise HTTPException(status_code=409, detail="This instance is already set up.") + if not state.check_setup_token(db, x_setup_token): + raise HTTPException(status_code=403, detail="Invalid or missing setup token.") + return db + + +@router.get("/status") +def setup_status(db: Session = Depends(get_db)) -> dict: + """Public: whether the instance still needs first-run setup.""" + return {"configured": state.is_configured(db)} + + +@router.get("/info") +def setup_info(db: Session = Depends(require_setup)) -> dict: + """Capabilities the wizard adapts to: whether secrets (Google creds, SMTP password) can be + stored — they need TOKEN_ENCRYPTION_KEY (set in env), so on a box without it the wizard hides + those steps and the operator stays on email+password only.""" + return {"secrets_manageable": sysconfig.secrets_manageable()} + + +@router.post("/admin") +def setup_admin(payload: dict, db: Session = Depends(require_setup)) -> dict: + """Create (or update) the first administrator. Active + verified immediately — the operator is + configuring the instance, so there's no email-verification / approval gate here.""" + email = (payload.get("email") or "").strip().lower() + password = payload.get("password") or "" + if "@" not in email: + raise HTTPException(status_code=400, detail="Enter a valid email address.") + if len(password) < PASSWORD_MIN_LEN: + raise HTTPException( + status_code=400, detail=f"Password must be at least {PASSWORD_MIN_LEN} characters." + ) + user = db.execute(select(User).where(User.email == email)).scalar_one_or_none() + if user is None: + user = User(email=email, role="admin") + db.add(user) + user.password_hash = hash_password(password) + user.role = "admin" + user.is_active = True + user.email_verified = True + db.commit() + return {"ok": True, "email": email} + + +@router.post("/config") +def setup_config(payload: dict, db: Session = Depends(require_setup)) -> dict: + """Persist provided DB-backed settings (Google creds, SMTP, quota…). Keys must be in the + sysconfig registry; empty values are skipped (left at the default).""" + saved: list[str] = [] + for key, value in (payload or {}).items(): + if sysconfig.spec(key) is None: + raise HTTPException(status_code=400, detail=f"Unknown setting: {key}") + if value is None or value == "": + continue + try: + sysconfig.set_value(db, key, value) + except (ValueError, RuntimeError) as exc: + raise HTTPException(status_code=400, detail=str(exc)) + saved.append(key) + return {"saved": saved} + + +@router.post("/test-email") +def setup_test_email(payload: dict, db: Session = Depends(require_setup)) -> dict: + """Send a test email to confirm the SMTP settings the wizard just saved.""" + to = (payload.get("to") or "").strip() + if "@" not in to: + raise HTTPException(status_code=400, detail="Enter a valid email address.") + if not email_mod.send_test(to): + raise HTTPException(status_code=400, detail="Couldn't send — check the SMTP settings.") + return {"ok": True} + + +@router.post("/finish") +def setup_finish(db: Session = Depends(require_setup)) -> dict: + """Complete setup: require that an admin exists, then mark the instance configured (which + invalidates the setup token and disables the wizard).""" + has_admin = db.execute(select(User).where(User.role == "admin")).first() is not None + if not has_admin: + raise HTTPException(status_code=400, detail="Create the admin account first.") + state.mark_configured(db) + return {"ok": True} diff --git a/backend/app/state.py b/backend/app/state.py index 34f56fa..80466c5 100644 --- a/backend/app/state.py +++ b/backend/app/state.py @@ -1,5 +1,7 @@ -"""Global admin-controlled app state (e.g. pausing background sync).""" +"""Global admin-controlled app state (e.g. pausing background sync, first-run setup).""" +import hashlib import logging +import secrets from sqlalchemy.orm import Session @@ -12,6 +14,10 @@ log = logging.getLogger("subfeed.state") MAINTENANCE_BATCH_MIN = 100 MAINTENANCE_BATCH_MAX = 100_000 +# Once configuration completes in this process it never reverts, so cache it to skip the per-request +# DB hit in the setup-mode gate (see main.setup_gate). Starts False; refreshed from the DB. +_configured_cache = False + def _row(db: Session) -> AppState: row = db.get(AppState, 1) @@ -34,6 +40,62 @@ def set_sync_paused(db: Session, paused: bool) -> None: log.info("Background sync %s", "paused" if paused else "resumed") +# --- First-run install wizard ------------------------------------------------------------ + +def is_configured(db: Session) -> bool: + return _row(db).configured + + +def setup_complete() -> bool: + """Fast, DB-free check for the request gate: True once configuration finished this process.""" + return _configured_cache + + +def is_configured_cached(db: Session) -> bool: + """Configured check that promotes the module cache once true (configuration is one-way).""" + global _configured_cache + if _configured_cache: + return True + if is_configured(db): + _configured_cache = True + return _configured_cache + + +def mark_configured(db: Session) -> None: + """Finish setup: flip the instance to configured and invalidate the setup token.""" + global _configured_cache + row = _row(db) + row.configured = True + row.setup_token_hash = None + db.add(row) + db.commit() + _configured_cache = True + log.info("Instance marked configured; setup wizard disabled.") + + +def _hash_token(raw: str) -> str: + return hashlib.sha256(raw.encode()).hexdigest() + + +def rotate_setup_token(db: Session) -> str: + """Generate a fresh one-time setup token, persist only its hash, and return the raw token + (logged at startup so the admin can open the wizard).""" + raw = secrets.token_urlsafe(24) + row = _row(db) + row.setup_token_hash = _hash_token(raw) + db.add(row) + db.commit() + return raw + + +def check_setup_token(db: Session, raw: str | None) -> bool: + """Whether `raw` matches the stored setup-token hash (constant-time).""" + if not raw: + return False + stored = _row(db).setup_token_hash + return stored is not None and secrets.compare_digest(stored, _hash_token(raw)) + + def get_maintenance_batch(db: Session) -> int: """Effective maintenance re-validation batch: the admin override if set, else the env/config default.""" diff --git a/backend/app/sysconfig.py b/backend/app/sysconfig.py index b5db3dc..51b3ad3 100644 --- a/backend/app/sysconfig.py +++ b/backend/app/sysconfig.py @@ -50,6 +50,10 @@ SPECS: tuple[ConfigSpec, ...] = ( ConfigSpec("autotag_title_sample", "int", "batch", "autotag_title_sample", min=1, max=1_000), # --- YouTube Data API key (secret; optional — public reads prefer it over OAuth) --- ConfigSpec("youtube_api_key", "str", "youtube", "youtube_api_key", secret=True), + # --- Google OAuth client (Sign in with Google; both encrypted, env fallback). Set from the + # install wizard / Configuration page so no restart is needed when the creds change. --- + ConfigSpec("google_client_id", "str", "google", "google_client_id", secret=True), + ConfigSpec("google_client_secret", "str", "google", "google_client_secret", secret=True), # --- Access / registration --- ConfigSpec("allow_registration", "bool", "access", "allow_registration"), ) diff --git a/backend/app/youtube/client.py b/backend/app/youtube/client.py index cc7ce09..0692171 100644 --- a/backend/app/youtube/client.py +++ b/backend/app/youtube/client.py @@ -66,8 +66,8 @@ class YouTubeClient: resp = self._http.post( GOOGLE_TOKEN_URL, data={ - "client_id": settings.google_client_id, - "client_secret": settings.google_client_secret, + "client_id": sysconfig.get_str(self.db, "google_client_id"), + "client_secret": sysconfig.get_str(self.db, "google_client_secret"), "refresh_token": refresh, "grant_type": "refresh_token", }, diff --git a/docker-compose.selfhost.yml b/docker-compose.selfhost.yml new file mode 100644 index 0000000..a646d11 --- /dev/null +++ b/docker-compose.selfhost.yml @@ -0,0 +1,67 @@ +# Self-hosting Siftlode — pulls the prebuilt image, no source build needed. +# +# 1. Run ./install.sh (or install.ps1 on Windows) once — it generates a .env with secrets. +# 2. docker compose -f docker-compose.selfhost.yml up -d +# 3. Open the setup wizard at the URL printed in the logs: +# docker compose -f docker-compose.selfhost.yml logs api | grep SETUP +# +# The .env only needs four values (the install script generates all of them): +# POSTGRES_PASSWORD, SECRET_KEY, TOKEN_ENCRYPTION_KEY, OAUTH_REDIRECT_URL +# Everything else — the admin account, Google sign-in, SMTP — is set in the web wizard on +# first run. See docs/self-hosting.md. + +services: + db: + image: postgres:16-alpine + environment: + POSTGRES_USER: ${POSTGRES_USER:-subfeed} + POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?POSTGRES_PASSWORD must be set (run install.sh)} + POSTGRES_DB: ${POSTGRES_DB:-subfeed} + volumes: + - siftlode_pgdata:/var/lib/postgresql/data + networks: [internal] + security_opt: + - no-new-privileges:true + healthcheck: + test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-subfeed} -d ${POSTGRES_DB:-subfeed}"] + interval: 10s + timeout: 5s + retries: 12 + restart: unless-stopped + + api: + image: forge.b1fr0st.eu/peter/siftlode:${IMAGE_TAG:-latest} + env_file: + - .env + environment: + DATABASE_URL: postgresql+psycopg://${POSTGRES_USER:-subfeed}:${POSTGRES_PASSWORD}@db:5432/${POSTGRES_DB:-subfeed} + # This instance owns the background scheduler (single writer). + SCHEDULER_ENABLED: "true" + depends_on: + db: + condition: service_healthy + networks: [internal] + ports: + # Reachable on the host's LAN at http://:8080. Put a reverse proxy (Caddy/Nginx) in + # front for HTTPS / public exposure — and set OAUTH_REDIRECT_URL to the https URL. + - "${HTTP_PORT:-8080}:8000" + security_opt: + - no-new-privileges:true + cap_drop: + - ALL + read_only: true + tmpfs: + - /tmp + healthcheck: + test: ["CMD", "python", "-c", "import urllib.request,sys; sys.exit(0 if urllib.request.urlopen('http://localhost:8000/healthz').status==200 else 1)"] + interval: 15s + timeout: 5s + retries: 5 + start_period: 30s + restart: unless-stopped + +volumes: + siftlode_pgdata: + +networks: + internal: diff --git a/docs/self-hosting.md b/docs/self-hosting.md new file mode 100644 index 0000000..bfb4cb0 --- /dev/null +++ b/docs/self-hosting.md @@ -0,0 +1,97 @@ +# Self-hosting Siftlode + +Run your own private Siftlode instance with Docker. You don't need the source code — the app runs +from a prebuilt image, and everything user-facing (your admin account, Google sign-in, email) is +configured in a web wizard on first start. There's no editing of config files by hand. + +## What you need + +- A machine with **Docker** and the **Docker Compose plugin** (Docker Desktop on Windows/macOS, + or Docker Engine on Linux). +- A few hundred MB of disk and ~1 GB RAM free. +- Optional: a domain name + reverse proxy if you want HTTPS / public access (see below). + +## 1. Get the files + +Download these into a new, empty folder: + +- `docker-compose.selfhost.yml` +- `install.sh` (Linux/macOS) **or** `install.ps1` (Windows) + +The app image is published at `forge.b1fr0st.eu/peter/siftlode` (public — no login to pull). + +## 2. Run the installer + +**Linux / macOS:** + +```bash +chmod +x install.sh +./install.sh +``` + +**Windows (PowerShell):** + +```powershell +./install.ps1 +``` + +The installer asks for the **public URL** where the instance will be reached (just press Enter for +`http://localhost:8080` to try it locally). It then: + +- generates the secrets it needs (`SECRET_KEY`, `TOKEN_ENCRYPTION_KEY`, a database password) into a + local `.env` file — keep that file private, +- pulls the image and starts the app + database, +- prints the **setup wizard URL**, which looks like `…/setup?token=…`. + +## 3. Finish in the web wizard + +Open the printed setup URL in your browser. The one-time token in it means only you (with access to +the server logs) can run setup. Then click through: + +1. **Admin account** — your email + a password. This is how you'll sign in. +2. **Google sign-in** *(optional)* — paste a Google OAuth client ID + secret to enable "Sign in with + Google" and pulling your YouTube subscriptions. Skip it to use email + password only. +3. **Email / SMTP** *(optional)* — an SMTP server so the app can send verification and notification + emails. Skip it — without email, new registrations are simply approved by you (the admin) instead. +4. **Finish** — the wizard disappears, the instance is now configured, and you land on the sign-in + page. Log in with the admin account you just created. + +That's it. You can change any of the optional settings later under the admin **Configuration** page. + +> The setup wizard only exists until you finish it. After that, the setup routes are disabled and +> the token is invalidated — there's no setup surface left on a configured instance. + +## Getting a Google OAuth client (optional) + +Only needed for "Sign in with Google" / YouTube access. In the +[Google Cloud Console](https://console.cloud.google.com/): create a project → **APIs & Services → +Credentials → Create credentials → OAuth client ID** → *Web application*. Add your instance's +`…/auth/callback` URL as an **Authorized redirect URI**, then copy the **client ID** and **secret** +into the wizard's Google step. (Enable the **YouTube Data API v3** for the project too.) + +## HTTPS / public access + +The app is served on port `8080` over plain HTTP, which is fine for a LAN or a quick trial. For +public access, put a reverse proxy (Caddy, Nginx, Traefik…) in front to terminate TLS, and set the +**public URL** in the installer to your `https://…` address (this also marks the session cookie +secure). If you've already run the installer, edit `OAUTH_REDIRECT_URL` in `.env` to the https +callback URL and `docker compose -f docker-compose.selfhost.yml up -d`. + +## Day-to-day + +```bash +# Update to the latest release +docker compose -f docker-compose.selfhost.yml pull +docker compose -f docker-compose.selfhost.yml up -d + +# Logs / status +docker compose -f docker-compose.selfhost.yml logs -f api +docker compose -f docker-compose.selfhost.yml ps + +# Stop +docker compose -f docker-compose.selfhost.yml down +``` + +Your data (accounts, subscriptions, playlists, the video catalog) lives in the `siftlode_pgdata` +Docker volume — back that up to keep your instance's state. Database migrations run automatically +when the app starts, so updating is just pull + up. diff --git a/frontend/src/App.tsx b/frontend/src/App.tsx index b1a03a6..d6523ad 100644 --- a/frontend/src/App.tsx +++ b/frontend/src/App.tsx @@ -22,6 +22,7 @@ import { hintsEnabled, setHintsEnabled } from "./lib/hints"; import { useConfirm } from "./components/ConfirmProvider"; import type { PrefsController } from "./components/SettingsPanel"; import Welcome from "./components/Welcome"; +import SetupWizard from "./components/SetupWizard"; import Header from "./components/Header"; import NavSidebar from "./components/NavSidebar"; import Sidebar from "./components/Sidebar"; @@ -265,6 +266,15 @@ export default function App() { }, []); // eslint-disable-line react-hooks/exhaustive-deps const queryClient = useQueryClient(); + // First-run install gate: a fresh instance reports configured=false and runs in setup mode. + // We check this before anything else and render the wizard; `me` is held back until we know the + // instance is set up (otherwise it would 503 against the setup-mode lock). + const setupQuery = useQuery({ + queryKey: ["setup-status"], + queryFn: api.setupStatus, + staleTime: Infinity, + }); + const needsSetup = setupQuery.data?.configured === false; // Poll the session so an account suspended/deleted by an admin is noticed even with no // interaction (option 1): the refetch 401s → the 401 handler below drops to the login page. // Only poll while signed in (data present) — polling on the public login page is pointless and @@ -272,6 +282,7 @@ export default function App() { const meQuery = useQuery({ queryKey: ["me"], queryFn: api.me, + enabled: setupQuery.isSuccess && !needsSetup, refetchInterval: (query) => (query.state.data ? 60_000 : false), }); @@ -445,6 +456,13 @@ export default function App() { // (we can't show our in-app confirm there), and unsaved prefs are local-only — they // revert to the saved server baseline on the next load — so there's nothing to lose. + // First-run: a fresh instance is in setup mode (all other routes are locked) → show the wizard. + if (setupQuery.isLoading) + return ( +
{t("common.loading")}
+ ); + if (needsSetup) return ; + if (meQuery.isLoading) return (
{t("common.loading")}
diff --git a/frontend/src/components/ConfigPanel.tsx b/frontend/src/components/ConfigPanel.tsx index b614eec..1da0e7a 100644 --- a/frontend/src/components/ConfigPanel.tsx +++ b/frontend/src/components/ConfigPanel.tsx @@ -12,7 +12,7 @@ import Tabs, { usePersistedTab } from "./Tabs"; // applied together via one Save/Discard bar (consistent with the Settings page); nothing hits // the server until Save. Group order is fixed where known so logically related settings (e.g. // Email/SMTP) stay together. -const GROUP_ORDER = ["access", "email", "youtube", "quota", "backfill", "shorts", "batch"]; +const GROUP_ORDER = ["access", "email", "youtube", "google", "quota", "backfill", "shorts", "batch"]; type SaveState = "idle" | "saving" | "saved" | "error"; export default function ConfigPanel() { diff --git a/frontend/src/components/SettingsPanel.tsx b/frontend/src/components/SettingsPanel.tsx index 465e988..156225f 100644 --- a/frontend/src/components/SettingsPanel.tsx +++ b/frontend/src/components/SettingsPanel.tsx @@ -389,34 +389,40 @@ function SignInMethods({ me }: { me: Me }) { const inputCls = "w-full bg-card border border-border rounded-xl px-3 py-2 text-sm outline-none focus:border-accent"; + // Offer Google only when this instance has Google OAuth configured (or the account is already + // linked — then we still show its "Connected" status even if the instance creds were removed). + const showGoogle = me.google_enabled || me.has_google; + return (
-
-
-
{t("settings.account.googleLink.title")}
-

- {me.has_google - ? t("settings.account.googleLink.connectedHint") - : t("settings.account.googleLink.connectHint")} -

+ {showGoogle && ( +
+
+
{t("settings.account.googleLink.title")}
+

+ {me.has_google + ? t("settings.account.googleLink.connectedHint") + : t("settings.account.googleLink.connectHint")} +

+
+ {me.has_google ? ( + + {t("settings.account.googleLink.connected")} + + ) : ( + + )}
- {me.has_google ? ( - - {t("settings.account.googleLink.connected")} - - ) : ( - - )} -
+ )} -
+
{t("settings.account.password.title")}
@@ -517,7 +523,8 @@ function Account({ me, onOpenWizard }: { me: Me; onOpenWizard: () => void }) { {t("settings.account.demoNotice")}

- ) : ( + ) : me.google_enabled ? ( + // YouTube access requires Google OAuth; hidden when this instance has no Google configured.

{t("settings.account.youtubeAccessIntro")} @@ -549,7 +556,7 @@ function Account({ me, onOpenWizard }: { me: Me; onOpenWizard: () => void }) { {t("settings.account.walkMeThrough")}

- )} + ) : null} {!me.is_demo && (
diff --git a/frontend/src/components/SetupWizard.tsx b/frontend/src/components/SetupWizard.tsx new file mode 100644 index 0000000..3ca8938 --- /dev/null +++ b/frontend/src/components/SetupWizard.tsx @@ -0,0 +1,273 @@ +import { useEffect, useState } from "react"; +import { useTranslation } from "react-i18next"; +import { Check, ChevronLeft, ChevronRight, Loader2, Send } from "lucide-react"; +import { api } from "../lib/api"; +import { setLanguage, type LangCode } from "../i18n"; +import LanguageSwitcher from "./LanguageSwitcher"; + +// First-run install wizard. Shown by App.tsx while the instance is unconfigured. The one-time +// setup token comes from the URL the app printed to the container logs (?token=…); every step +// posts it back as the X-Setup-Token header. On finish the instance flips to configured, the +// wizard disappears, and the operator signs in with the admin account they just created. +type StepId = "intro" | "admin" | "google" | "smtp" | "finish"; + +const PASSWORD_MIN = 10; + +export default function SetupWizard() { + const { t, i18n } = useTranslation(); + const [token] = useState(() => new URLSearchParams(window.location.search).get("token") ?? ""); + const [info, setInfo] = useState<{ secrets_manageable: boolean } | null>(null); + const [tokenError, setTokenError] = useState(false); + + useEffect(() => { + if (!token) { + setTokenError(true); + return; + } + api.setupInfo(token).then(setInfo).catch(() => setTokenError(true)); + }, [token]); + + // Step state. + const [stepIdx, setStepIdx] = useState(0); + const [busy, setBusy] = useState(false); + const [error, setError] = useState(""); + // Admin account. + const [email, setEmail] = useState(""); + const [password, setPassword] = useState(""); + // Google OAuth (optional). + const [gid, setGid] = useState(""); + const [gsecret, setGsecret] = useState(""); + // SMTP (optional). + const [smtp, setSmtp] = useState({ host: "", port: "587", user: "", from: "", password: "" }); + const [testTo, setTestTo] = useState(""); + const [testState, setTestState] = useState<"idle" | "sending" | "ok" | "fail">("idle"); + + if (tokenError) return ; + if (!info) return ; + + // Steps adapt to the instance: Google + SMTP need encrypted secret storage (TOKEN_ENCRYPTION_KEY). + const steps: StepId[] = [ + "intro", + "admin", + ...(info.secrets_manageable ? (["google", "smtp"] as StepId[]) : []), + "finish", + ]; + const step = steps[stepIdx]; + const go = (delta: number) => { + setError(""); + setStepIdx((i) => Math.min(steps.length - 1, Math.max(0, i + delta))); + }; + + // Each step's "Next" action persists what it collected, then advances. Optional steps with empty + // fields just advance (skip). Errors surface inline (the setup calls use the quiet flag). + async function next() { + setError(""); + setBusy(true); + try { + if (step === "admin") { + if (!/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(email)) + throw { detail: t("setup.admin.invalidEmail") }; + if (password.length < PASSWORD_MIN) + throw { detail: t("setup.admin.shortPassword", { n: PASSWORD_MIN }) }; + await api.setupAdmin(token, email, password); + } else if (step === "google" && (gid.trim() || gsecret.trim())) { + if (!gid.trim() || !gsecret.trim()) throw { detail: t("setup.google.bothRequired") }; + await api.setupConfig(token, { google_client_id: gid.trim(), google_client_secret: gsecret.trim() }); + } else if (step === "smtp" && smtp.host.trim()) { + await api.setupConfig(token, { + smtp_host: smtp.host.trim(), + smtp_port: Number(smtp.port) || 587, + smtp_user: smtp.user.trim(), + smtp_from: smtp.from.trim(), + smtp_password: smtp.password, + }); + } else if (step === "finish") { + await api.setupFinish(token); + window.location.href = "/"; // configured now → reloads into the login page + return; + } + go(1); + } catch (e: any) { + setError(e?.detail ?? t("setup.genericError")); + } finally { + setBusy(false); + } + } + + async function sendTest() { + setTestState("sending"); + try { + // Persist the SMTP fields first so the test uses them, then send. + if (smtp.host.trim()) + await api.setupConfig(token, { + smtp_host: smtp.host.trim(), + smtp_port: Number(smtp.port) || 587, + smtp_user: smtp.user.trim(), + smtp_from: smtp.from.trim(), + smtp_password: smtp.password, + }); + await api.setupTestEmail(token, testTo.trim()); + setTestState("ok"); + } catch { + setTestState("fail"); + } + } + + const inputCls = + "w-full bg-card border border-border rounded-xl px-3 py-2 text-sm outline-none focus:border-accent"; + + return ( + +
+
+
+ Siftlode +
+ +
+ + {/* Step progress dots */} +
+ {steps.map((s, i) => ( +
+ ))} +
+ +
+ {step === "intro" && ( +
+ )} + + {step === "admin" && ( +
+ setEmail(e.target.value)} + placeholder={t("setup.admin.email")} + autoComplete="username" + className={inputCls} + /> + setPassword(e.target.value)} + placeholder={t("setup.admin.password", { n: PASSWORD_MIN })} + autoComplete="new-password" + className={inputCls} + /> +
+ )} + + {step === "google" && ( +
+ setGid(e.target.value)} placeholder={t("setup.google.clientId")} className={inputCls} /> + setGsecret(e.target.value)} placeholder={t("setup.google.clientSecret")} className={inputCls} /> +

{t("setup.google.skipHint")}

+
+ )} + + {step === "smtp" && ( +
+ setSmtp({ ...smtp, host: e.target.value })} placeholder={t("setup.smtp.host")} className={inputCls} /> +
+ setSmtp({ ...smtp, port: e.target.value })} placeholder={t("setup.smtp.port")} className={`${inputCls} w-24`} /> + setSmtp({ ...smtp, user: e.target.value })} placeholder={t("setup.smtp.user")} className={inputCls} /> +
+ setSmtp({ ...smtp, from: e.target.value })} placeholder={t("setup.smtp.from")} className={inputCls} /> + setSmtp({ ...smtp, password: e.target.value })} placeholder={t("setup.smtp.password")} className={inputCls} /> + {smtp.host.trim() && ( +
+ setTestTo(e.target.value)} placeholder={t("setup.smtp.testTo")} className={inputCls} /> + +
+ )} + {testState === "ok" &&

{t("setup.smtp.testOk")}

} + {testState === "fail" &&

{t("setup.smtp.testFail")}

} +

{t("setup.smtp.skipHint")}

+
+ )} + + {step === "finish" && ( +
+ )} + + {error &&

{error}

} + +
+ + +
+
+
+ + ); +} + +function Centered({ children }: { children: React.ReactNode }) { + return ( +
{children}
+ ); +} + +function Section({ + title, + desc, + children, +}: { + title: string; + desc: string; + children?: React.ReactNode; +}) { + return ( +
+
+

{title}

+

{desc}

+
+ {children} +
+ ); +} + +function TokenError() { + const { t } = useTranslation(); + return ( +
+

{t("setup.token.title")}

+

{t("setup.token.body")}

+
+ ); +} diff --git a/frontend/src/components/Welcome.tsx b/frontend/src/components/Welcome.tsx index df0daa9..3d91468 100644 --- a/frontend/src/components/Welcome.tsx +++ b/frontend/src/components/Welcome.tsx @@ -243,6 +243,13 @@ function AuthCard() { const [password, setPassword] = useState(""); const [busy, setBusy] = useState(false); const [error, setError] = useState(""); + // Whether to offer "Continue with Google" — hidden when the instance has no Google OAuth + // configured. Optimistic (most instances have it); the rare Google-less instance just sees it + // disappear once the config loads. + const [googleEnabled, setGoogleEnabled] = useState(true); + useEffect(() => { + api.authConfig().then((c) => setGoogleEnabled(c.google_enabled)).catch(() => {}); + }, []); const [done, setDone] = useState(""); // success/info message replacing the form // Explicit demo entry (replaces the old hidden probe): a labelled email field, still gated @@ -423,12 +430,14 @@ function AuthCard() { {t("welcome.auth.or")}
- - {t("welcome.auth.google")} - + {googleEnabled && ( + + {t("welcome.auth.google")} + + )} {!showDemo ? (