giersig.eu/indiekit-server
1
0
Fork 0
Code Issues Actions Packages Projects Releases Activity
79 Commits 1 Branch 0 Tags
8daa96afe22b19f18790bb56014429c3789e2376
Go to file
Clone
Open with VS Code Open with VSCodium Open with Intellij IDEA
Download ZIP Download TAR.GZ Download BUNDLE

README.md

Indieweb/kit Blog Server

Admin login

  • The IndieKit admin uses root auth/session paths (for example: /session/login, /auth, /auth/new-password).
  • Login uses PASSWORD_SECRET (bcrypt hash), not INDIEKIT_PASSWORD.
  • If no PASSWORD_SECRET exists yet, open /auth/new-password once to generate it.
  • If login is blocked because PASSWORD_SECRET is missing/invalid, set INDIEKIT_ALLOW_PASSWORD_SETUP=1 temporarily, restart, generate a new hash via /auth/new-password, set PASSWORD_SECRET to that hash, then remove INDIEKIT_ALLOW_PASSWORD_SETUP.
  • If login appears passwordless, first check for an existing authenticated session cookie. Use /session/logout to force a fresh login challenge.
  • Upstream IndieKit auto-authenticates in dev mode (NODE_ENV=development). This repository patches that behavior so dev auto-auth only works when INDIEKIT_ALLOW_DEV_AUTH=1 is explicitly set.
  • Production startup now fails closed when auth/session settings are unsafe (NODE_ENV not production, INDIEKIT_ALLOW_DEV_AUTH=1, weak SECRET, missing/invalid PASSWORD_SECRET, or empty-password hash).
  • Post management UI should use /posts (@indiekit/endpoint-posts.mountPath).
  • Do not set post-management mountPath to frontend routes like /blog, otherwise backend publishing can be shadowed by the public site.

Backend endpoints

  • Configured endpoint mount paths:
  • Posts management: /posts
  • Files: /files
  • Webmentions moderation + API: /webmentions
  • Homepage builder UI + API: /homepage
  • Conversations + API: /conversations
  • GitHub activity + API: /github
  • Funkwhale activity + API: /funkwhale
  • Last.fm activity + API: /lastfmapi
  • ActivityPub federation + admin reader: /activitypub
  • ActivityPub discovery: /.well-known/webfinger, /nodeinfo/2.1

MongoDB

  • Preferred: set MONGO_USERNAME and MONGO_PASSWORD explicitly; config builds the URL from MONGO_USERNAME, MONGO_PASSWORD, MONGO_HOST, MONGO_PORT, MONGO_DATABASE, MONGO_AUTH_SOURCE.
  • You can still use a full MONGO_URL (example: mongodb://user:pass@host:27017/indiekit?authSource=admin).
  • If both MONGO_URL and MONGO_USERNAME/MONGO_PASSWORD are set, decomposed credentials take precedence by default to avoid stale URL mismatches. Set MONGO_PREFER_URL=1 to force MONGO_URL precedence.
  • Startup scripts now fail fast when MONGO_URL is absent and MONGO_USERNAME is missing, to avoid silent auth mismatches.
  • Startup now runs scripts/preflight-mongo-connection.mjs before boot. Preflight is strict by default and aborts start on Mongo auth/connect failures; set REQUIRE_MONGO=0 to bypass strict mode intentionally.
  • For MongoServerError: Authentication failed, first verify MONGO_PASSWORD, then try MONGO_AUTH_SOURCE=admin.

Content paths

  • This setup writes post files to the content repo blog under content/.
  • Photo upload binaries are written to images/{filename} and published at ${PUBLICATION_URL}/images/{filename}.
  • Current paths in publication.postTypes are:
  • content/articles/{slug}.md
  • content/notes/{slug}.md
  • content/bookmarks/{slug}.md
  • content/likes/{slug}.md
  • content/photos/{slug}.md
  • content/replies/{slug}.md
  • content/pages/{slug}.md
  • If these paths do not match the content repo structure, edit/delete actions can fail with GitHub Not Found.
  • Reposts are configured as a dedicated post type (repost) and stored at content/reposts/{slug}.md.

Post URLs

  • Current post URLs in publication.postTypes are:
  • https://blog.giersig.eu/articles/{slug}/
  • https://blog.giersig.eu/notes/{slug}/
  • https://blog.giersig.eu/bookmarks/{slug}/
  • https://blog.giersig.eu/likes/{slug}/
  • https://blog.giersig.eu/photos/{slug}/
  • https://blog.giersig.eu/replies/{slug}/
  • https://blog.giersig.eu/{slug}/ (page post type)

GitHub tokens

  • Recommended for two-repo setups:
  • GH_CONTENT_TOKEN: token for content repo (blog), used by @indiekit/store-github.
  • GH_ACTIVITY_TOKEN: token for GitHub dashboard/activity endpoint, used by @rmdes/indiekit-endpoint-github.
  • GITHUB_USERNAME: GitHub user/owner name.
  • Backward compatibility: if GH_CONTENT_TOKEN or GH_ACTIVITY_TOKEN are not set, config falls back to GITHUB_TOKEN.

Listening tokens

  • Funkwhale endpoint requirements:
  • FUNKWHALE_INSTANCE (for example https://your-funkwhale.example, root server URL only)
  • FUNKWHALE_USERNAME
  • FUNKWHALE_TOKEN (read API token)
  • Last.fm endpoint requirements:
  • LASTFM_API_KEY
  • LASTFM_USERNAME
  • Listening endpoint plugins target Node.js 20+; older runtimes can produce inconsistent fetch/JSON behavior.
  • If FUNKWHALE_INSTANCE points to a host that does not expose Funkwhale's API routes, API responses now degrade to empty data instead of repeated 500 errors.
  • If these variables are missing, the endpoints still exist but return empty activity until credentials are configured.

ActivityPub

  • ActivityPub federation is enabled via @rmdes/indiekit-endpoint-activitypub.
  • Actor handle resolution order is: AP_HANDLE, then ACTIVITYPUB_HANDLE, then GITHUB_USERNAME, then publication hostname first label.
  • Actor profile seed values come from AUTHOR_NAME, AUTHOR_BIO, AUTHOR_AVATAR, and SITE_DESCRIPTION.
  • AUTHOR_AVATAR can be absolute (https://...) or slash-relative (/images/avatar.jpg); startup normalizes it to an absolute URL.
  • Optional ActivityPub variables:
  • AP_ALSO_KNOWN_AS (Mastodon migration alias URL)
  • AP_LOG_LEVEL (debug|info|warning|error|fatal, default info)
  • AP_DEBUG (1 or true enables debug dashboard)
  • AP_DEBUG_PASSWORD (required when debug dashboard is enabled)
  • REDIS_URL (recommended for production delivery queue durability)
  • Startup preflight scripts/preflight-activitypub-rsa-key.mjs ensures ap_keys contains a usable RSA key pair (publicKeyPem + privateKeyPem) so outgoing inbox deliveries are HTTP-signed and not rejected with Request not signed.
  • Startup preflight scripts/preflight-activitypub-profile-urls.mjs normalizes existing ActivityPub profile URL fields in MongoDB (url, icon, image, alsoKnownAs) so WebFinger/actor responses do not fail on invalid URL values.
  • The ActivityPub locale patch creates/repairs locales/de.json from locales/en.json so backend UI keys do not render as raw activitypub.* translation strings when SITE_LOCALE=de.
  • Quick verification commands:
  • curl -s "https://blog.giersig.eu/.well-known/webfinger?resource=acct:<handle>@blog.giersig.eu" | jq .
  • curl -s -H "Accept: application/activity+json" "https://blog.giersig.eu/" | jq .
  • curl -s "https://blog.giersig.eu/nodeinfo/2.1" | jq .
  • If a reverse proxy serves static HTML, ensure AP requests are proxied to Indiekit for /activitypub*, /.well-known/*, /nodeinfo/*, and content-negotiated Accept: application/activity+json / application/ld+json requests on / and post URLs.

Startup script

  • start.sh is intentionally ignored by Git (.gitignore) so server secrets are not committed.
  • Use start.example.sh as the tracked template and keep real credentials in environment variables (or .env on the server).
  • Startup scripts parse .env with the dotenv parser (not shell source), so values containing spaces are handled safely.
  • Startup scripts run preflight + patch helpers before boot (scripts/preflight-production-security.mjs, scripts/preflight-mongo-connection.mjs, scripts/preflight-activitypub-rsa-key.mjs, scripts/preflight-activitypub-profile-urls.mjs, scripts/patch-lightningcss.mjs, scripts/patch-endpoint-media-scope.mjs, scripts/patch-endpoint-media-sharp-runtime.mjs, scripts/patch-frontend-sharp-runtime.mjs, scripts/patch-endpoint-files-upload-route.mjs, scripts/patch-endpoint-files-upload-locales.mjs, scripts/patch-endpoint-activitypub-locales.mjs, scripts/patch-frontend-serviceworker-file.mjs, scripts/patch-conversations-collection-guards.mjs, scripts/patch-indiekit-routes-rate-limits.mjs, scripts/patch-indiekit-error-production-stack.mjs, scripts/patch-indieauth-devmode-guard.mjs, scripts/patch-listening-endpoint-runtime-guards.mjs).
  • The production security preflight blocks startup on insecure auth/session configuration and catches empty-password bcrypt hashes.
  • One-time recovery mode is available with INDIEKIT_ALLOW_PASSWORD_SETUP=1 to bootstrap/reset PASSWORD_SECRET when locked out. Remove this flag after setting a valid hash.
  • The media scope patch fixes a known upstream issue where file uploads can fail if the token scope is create update delete without explicit media.
  • The ActivityPub RSA key preflight repairs or creates a usable type="rsa" key document in ap_keys, so outgoing federation requests can be signed and accepted by stricter inboxes.
  • The ActivityPub profile URL preflight repairs invalid URL fields in the ap_profile document (for example relative icon paths), preventing /.well-known/webfinger and actor responses from failing with TypeError: Invalid URL.
  • The media sharp runtime patch makes image transformation resilient on FreeBSD: if sharp cannot load, uploads continue without resize/rotation instead of crashing the server process.
  • The frontend sharp runtime patch makes icon generation non-fatal on FreeBSD when sharp cannot load, preventing startup crashes in asset controller imports.
  • The files upload route patch fixes browser multi-upload by posting to /files/upload (session-authenticated) instead of direct /media calls without bearer token.
  • The files upload locale patch adds missing files.upload.dropText/files.upload.browse/files.upload.submitMultiple labels in endpoint locale files so UI text does not render raw translation keys.
  • The ActivityPub locale patch backfills missing de locale keys from the endpoint's en locale and applies German admin title labels for notifications/profile.
  • The frontend serviceworker patch ensures @indiekit/frontend/lib/serviceworker.js exists at runtime, forces network-only handling for /auth and /session pages, patches frontend layout templates to unregister stale service workers and clear caches on load, and suppresses sidebar rendering whenever app--minimalui is present.
  • The conversations guard patch prevents Cannot read properties of undefined (reading 'find') when the conversation_items collection is temporarily unavailable.
  • The indiekit routes rate-limit patch (ported from rmdes/indiekit-cloudron) keeps strict limits on /session/*, applies generous limits to public API/well-known routes, and removes extra rate limiting from authenticated routes to avoid admin-side 429 spikes.
  • The indiekit error stack patch (ported from rmdes/indiekit-cloudron) suppresses stack traces in production error pages/JSON responses to avoid leaking internal runtime details.
  • The indieauth dev-mode guard patch prevents accidental production auth bypass by requiring explicit INDIEKIT_ALLOW_DEV_AUTH=1 to enable dev auto-login, and broadens safe local redirect validation to allow common path characters (-, ., %) used by routes such as /auth/new-password.
Reference in New Issue View Git Blame Copy Permalink
Description
Indiekit deployment config
https://blog.giersig.eu
Readme 65 MiB
Languages
JavaScript 98.3%
Shell 1.7%