### Build and start production app Source: https://github.com/foldergram/foldergram/blob/main/docs/installation.md Run `pnpm build` to build the server and client, then `pnpm start` to launch the production app. The docs site is not built by `pnpm build`. ```bash pnpm build pnpm start ``` -------------------------------- ### Source Install for Development Source: https://github.com/foldergram/foldergram/blob/main/docs/installation.md Install dependencies, copy the environment template, and start the development server. Both pnpm dev and pnpm start run pending SQLite migrations automatically before opening the persistent database. ```bash pnpm install cp .env.example .env pnpm dev ``` -------------------------------- ### Source Install Update Commands Source: https://github.com/foldergram/foldergram/blob/main/docs/installation.md Stops the server, installs locked dependencies, rebuilds, and starts the server. Run after backing up configured data and updating the checkout. ```bash pnpm install --frozen-lockfile pnpm build pnpm start ``` -------------------------------- ### Media folder structure example Source: https://github.com/foldergram/foldergram/blob/main/docs/installation.md Illustrates a valid structure for placing media under data/gallery. Loose files directly in the gallery root are ignored. ```text data/ gallery/ trips/ oslo/ IMG_0001.jpg clip-01.mp4 family/ summer-2024/ porch.webp ``` -------------------------------- ### Production build and start from source Source: https://github.com/foldergram/foldergram/blob/main/README.md Builds and starts the production server from source. Then open http://localhost:4141. ```bash pnpm build pnpm start # or npm run build npm start ``` -------------------------------- ### Optional Developer Entry Points Source: https://github.com/foldergram/foldergram/blob/main/docs/installation.md Runs the development servers for the server, client, and docs separately. Useful for local development. ```bash pnpm dev:server pnpm dev:client pnpm dev:docs ``` -------------------------------- ### Update and Start Docker Compose Service Source: https://github.com/foldergram/foldergram/blob/main/docs/installation.md Pulls the updated image, starts the service, and shows the last 100 log lines. Pending SQLite migrations run automatically before requests are served. ```bash docker compose pull foldergram docker compose up -d foldergram docker compose logs --tail=100 foldergram ``` -------------------------------- ### Start development workspace with pnpm or npm Source: https://github.com/foldergram/foldergram/blob/main/README.md Starts the development workspace. Server startup applies pending SQLite migrations automatically. ```bash pnpm dev # or npm run dev ``` -------------------------------- ### Expected folder layout Source: https://github.com/foldergram/foldergram/blob/main/docs/installation.md Shows the expected directory structure after creating the working folder and gallery folder. ```text foldergram/ docker-compose.yml data/ gallery/ example-album/ ``` -------------------------------- ### Useful commands for Docker, migrations, and builds Source: https://github.com/foldergram/foldergram/blob/main/docs/quick-start.md Common operations: start/stop Docker containers, run database migrations, rescan media, run tests, build and start the app, and build docs. Use these after initial setup for routine tasks. ```bash docker compose up -d docker compose down pnpm migrate pnpm rescan pnpm test pnpm build pnpm start pnpm build:docs ``` -------------------------------- ### Build Docs with pnpm build:docs Source: https://github.com/foldergram/foldergram/blob/main/docs/installation.md Builds the VitePress documentation site separately from the main application. The deploy workflow publishes the output to ./docs/.vitepress/dist. ```bash pnpm build:docs ``` -------------------------------- ### Install dependencies with pnpm or npm Source: https://github.com/foldergram/foldergram/blob/main/README.md Installs project dependencies. pnpm is preferred, but npm is also supported. ```bash pnpm install # or npm install ``` -------------------------------- ### Docker Compose Image Tag Source: https://github.com/foldergram/foldergram/blob/main/docs/installation.md Use the latest image tag in docker-compose.yml to follow stable releases. ```yaml image: ghcr.io/foldergram/foldergram:latest ``` -------------------------------- ### Create local env file Source: https://github.com/foldergram/foldergram/blob/main/README.md Copies the example environment file to .env for local configuration. ```bash cp .env.example .env ``` -------------------------------- ### Start Docker container Source: https://github.com/foldergram/foldergram/blob/main/README.md Starts the Foldergram container in detached mode. Container startup runs pending SQLite migrations automatically before the app opens the library database. ```bash docker compose up -d ``` -------------------------------- ### GET /api/folders paginated response example Source: https://github.com/foldergram/foldergram/blob/main/docs/api.md Example response for the paginated directory endpoint when query parameters are supplied. The response includes items, page, limit, total, and hasMore. total counts all matching folders across pages. ```json { "items": [], "page": 1, "limit": 50, "total": 0, "hasMore": false } ``` -------------------------------- ### GET /api/folders/:slug/images response example Source: https://github.com/foldergram/foldergram/blob/main/docs/api.md Example response for the folder images endpoint, including a folder summary object and pagination fields. The folder summary includes hasAvatarStory and avatarUrl for client-side story entry decisions. ```json { "folder": { "id": 1, "slug": "oslo", "name": "oslo", "description": null, "folderPath": "trips/oslo", "breadcrumb": "trips", "imageCount": 12, "videoCount": 3, "latestImageMtimeMs": 1700000000000, "hasAvatarStory": false, "avatarImageId": 42, "avatarUrl": "/thumbnails/ab/abcd1234ef567890abcd1234ef567890.webp?v=4" }, "items": [], "page": 1, "limit": 24, "total": 12, "hasMore": false } ``` -------------------------------- ### Run browser regression tests Source: https://github.com/foldergram/foldergram/blob/main/docs/development.md Runs the browser test suite, which builds the client and starts a temporary preview on 127.0.0.1:4173. Uses mock API responses and fixtures, so it does not start the backend or read your gallery. Failure screenshots and traces are saved in client/test-results/. ```bash pnpm test:browser ``` -------------------------------- ### Install Chromium for browser tests Source: https://github.com/foldergram/foldergram/blob/main/docs/development.md Installs the Chromium browser required for the Playwright browser regression suite. Run once before executing the browser tests. ```bash pnpm --filter @foldergram/client exec playwright install chromium ``` -------------------------------- ### Create Foldergram folder and navigate Source: https://github.com/foldergram/foldergram/blob/main/README.md Creates a new directory named 'foldergram' and moves into it as the first step of the Docker installation. ```bash mkdir foldergram cd foldergram ``` -------------------------------- ### Stop Docker Compose Service Source: https://github.com/foldergram/foldergram/blob/main/docs/installation.md Stops the Foldergram container before taking a backup of host directories mounted by Compose. Ensures a consistent SQLite backup. ```bash docker compose stop foldergram ``` -------------------------------- ### GET /api/admin/scan-progress Source: https://github.com/foldergram/foldergram/blob/main/docs/api.md Returns the admin-detailed live scan payload. This route is read-only but admin-only. It uses the same overall shape as GET /api/scan-progress, with additional details such as populated currentFile and currentFolder, operation.id, operation.controls, recentIssues, and full lastCompletedScan. ```APIDOC ## GET /api/admin/scan-progress ### Description Returns the admin-detailed live scan payload. This route is read-only but admin-only. It uses the same overall shape as GET /api/scan-progress, with additional details such as populated currentFile and currentFolder, operation.id, operation.controls, recentIssues, and full lastCompletedScan. ### Method GET ### Endpoint /api/admin/scan-progress ### Response #### Success Response (200) - **currentFile** (string) - Populated when the active operation can identify a source path. - **currentFolder** (string) - Populated when the active operation can identify a source path. - **operation.id** (string) - Identifies a local operation across its source runs. - **operation.controls** (array) - Lists its currently available actions. - **recentIssues** (array) - Returns up to ten recent failed, unavailable, or error-bearing runs for acknowledgement. - **lastCompletedScan** (object) - The full terminal scan record, including `error_text`. ### Notes - When a run finishes as `completed_with_errors`, `error_text` contains a short sample plus the full report path under `/scan-errors/`. ``` -------------------------------- ### Set GALLERY_EXCLUDED_FOLDERS in docker-compose.yml Source: https://github.com/foldergram/foldergram/blob/main/README.md Example environment variable to skip unwanted source folders from the first scan. Add under the Compose 'environment:' block. ```yaml GALLERY_EXCLUDED_FOLDERS: "@eaDir,thumbnails,Archive/cache" ``` -------------------------------- ### GET /api/admin/places/status Source: https://github.com/foldergram/foldergram/blob/main/docs/api.md Returns the status of the places database preparation. This route is read-only but admin-only. ```APIDOC ## GET /api/admin/places/status ### Description Returns the status of the places database preparation. This route is read-only but admin-only. ### Method GET ### Endpoint /api/admin/places/status ### Response #### Success Response (200) - **prepared** (boolean) - Whether the places database is prepared. - **databasePath** (string) - Path to the geonames SQLite database. - **metadata** (object|null) - When prepared, includes source, sourceUrl, importedAt, and rowCount. #### Response Example ```json { "prepared": false, "databasePath": "/path/to/geonames.sqlite", "metadata": null } ``` ``` -------------------------------- ### GET /api/feed Source: https://github.com/foldergram/foldergram/blob/main/docs/api.md Returns a paginated mixed-media feed with images and videos. ```APIDOC ## GET /api/feed ### Description Returns a paginated mixed-media feed with images and videos. ### Method GET ### Endpoint /api/feed ### Parameters #### Query Parameters - **page** (integer) - Optional - Default `1`, minimum `1`. - **limit** (integer) - Optional - Default `24`, minimum `1`, maximum `60`. - **mode** (string) - Optional - Default `random`. Allowed values: `recent`, `rediscover`, `random`. - **seed** (integer) - Optional - Random seed for `random` mode. ### Response #### Success Response (200) - **mode** (string) - Feed mode - **items** (array) - Feed items (images and videos) - **page** (integer) - Current page - **limit** (integer) - Items per page - **total** (integer) - Total items - **hasMore** (boolean) - Whether more items exist #### Response Example ```json { "mode": "recent", "items": [], "page": 1, "limit": 24, "total": 0, "hasMore": false } ``` ``` -------------------------------- ### GET /api/places/:slug Source: https://github.com/foldergram/foldergram/blob/main/docs/api.md Returns one place detail record using the same shape as a place item from `GET /api/places`. ```APIDOC ## [GET] /api/places/:slug ### Description Returns one place detail record using the same shape as a place item from `GET /api/places`. ### Method GET ### Endpoint /api/places/:slug ### Errors - `404` with `{"message":"Place not found"}` ``` -------------------------------- ### GET /api/auth/status Source: https://github.com/foldergram/foldergram/blob/main/docs/api.md Returns the current auth state for the browser session. ```APIDOC ## GET /api/auth/status ### Description Returns the current auth state for the browser session. ### Method GET ### Endpoint /api/auth/status ### Response #### Success Response (200) - **enabled** (boolean) - Whether auth is enabled - **authenticated** (boolean) - Whether the session is authenticated - **role** (string) - User role - **accessMode** (string) - Access mode - **likesMode** (string) - Likes mode - **defaultLocale** (string) - Saved app-wide default locale - **capabilities** (object) - User capabilities - **canManageLibrary** (boolean) - Can manage library - **canDeleteMedia** (boolean) - Can delete media - **canAccessSettings** (boolean) - Can access settings - **canUseSharedLikes** (boolean) - Can use shared likes - **canUseLocalFavorites** (boolean) - Can use local favorites - **canUseSharedCollections** (boolean) - Can use shared collections - **canUseLocalCollections** (boolean) - Can use local collections #### Response Example ```json { "enabled": true, "authenticated": false, "role": "anonymous", "accessMode": "public", "likesMode": "local", "defaultLocale": "zh", "capabilities": { "canManageLibrary": false, "canDeleteMedia": false, "canAccessSettings": false, "canUseSharedLikes": false, "canUseLocalFavorites": true, "canUseSharedCollections": false, "canUseLocalCollections": true } } ``` ``` -------------------------------- ### Example of a folder structure that will be indexed Source: https://github.com/foldergram/foldergram/blob/main/docs/troubleshooting.md Shows a gallery layout that Foldergram will index because the oslo folder directly contains supported media (IMG_0001.jpg). ```text gallery/ trips/ oslo/ IMG_0001.jpg ``` -------------------------------- ### Rerun SQLite migrations with pnpm migrate Source: https://github.com/foldergram/foldergram/blob/main/docs/troubleshooting.md For source installs, rerun the migration step directly after an upgrade stops during startup. Check that DB_DIR exists and is writable, the database volume or bind mount points to the intended location, and the filesystem has enough free space before running. ```bash pnpm migrate ``` -------------------------------- ### GET /api/folders/:slug Source: https://github.com/foldergram/foldergram/blob/main/docs/api.md Returns one folder summary. The response uses the same shape as folder items from `GET /api/folders`, including `hasAvatarStory`. ```APIDOC ## GET /api/folders/:slug ### Description Returns one folder summary. The response uses the same shape as folder items from `GET /api/folders`, including `hasAvatarStory` so the client can decide whether the folder avatar should open a story entry point. ### Method GET ### Endpoint /api/folders/:slug ### Parameters #### Path Parameters - **slug** (string) - Required - The folder slug. ### Response #### Success Response (200) - **id** (integer) - Folder ID. - **slug** (string) - Folder slug. - **name** (string) - Folder name. - **description** (string|null) - Folder description. - **folderPath** (string) - Folder path. - **breadcrumb** (string) - Breadcrumb. - **imageCount** (integer) - Number of images. - **videoCount** (integer) - Number of videos. - **latestImageMtimeMs** (integer) - Latest image modification time in milliseconds. - **hasAvatarStory** (boolean) - Whether the folder has an avatar story. - **avatarImageId** (integer) - Avatar image ID. - **avatarUrl** (string) - Avatar URL. ### Errors - `404` with `{"message":"Folder not found"}` if the slug is missing. ``` -------------------------------- ### Recommended local .env configuration Source: https://github.com/foldergram/foldergram/blob/main/docs/configuration.md Use this .env file for local development. It sets the runtime ports, data directories, and scan behavior. SERVER_PORT defaults to 4141 unless overridden in Docker Compose or at process start. ```bash NODE_ENV=development SERVER_PORT=4141 DEV_SERVER_PORT=4140 DEV_CLIENT_PORT=4141 DATA_ROOT=./data GALLERY_ROOT=./data/gallery GALLERY_EXCLUDED_FOLDERS= DB_DIR=./data/db THUMBNAILS_DIR=./data/thumbnails PREVIEWS_DIR=./data/previews IMAGE_DETAIL_SOURCE=preview DERIVATIVE_MODE=eager LOG_VERBOSE=0 SCAN_MEDIA_ERROR_MODE=skip SCAN_DISCOVERY_CONCURRENCY=4 SCAN_DERIVATIVE_CONCURRENCY=4 PUBLIC_DEMO_MODE=0 CSRF_TRUSTED_ORIGINS= ``` -------------------------------- ### GET /api/health Source: https://github.com/foldergram/foldergram/blob/main/docs/api.md Returns process-level health plus storage state. ```APIDOC ## GET /api/health ### Description Returns process-level health plus storage state. ### Method GET ### Endpoint /api/health ### Response #### Success Response (200) - **ok** (boolean) - Health status - **timestamp** (string) - Current timestamp - **storage** (object) - Storage state - **available** (boolean) - Storage availability - **reason** (string|null) - Reason if unavailable - **usingInMemoryDatabase** (boolean) - Whether using in-memory database #### Response Example ```json { "ok": true, "timestamp": "2026-03-16T12:34:56.000Z", "storage": { "available": true, "reason": null, "usingInMemoryDatabase": false } } ``` ``` -------------------------------- ### GET /api/admin/stats Source: https://github.com/foldergram/foldergram/blob/main/docs/api.md Returns the full admin operational payload. This route is read-only but admin-only, extending GET /api/status with additional fields. ```APIDOC ## GET /api/admin/stats ### Description Returns the full admin operational payload. This route is read-only but admin-only, extending GET /api/status with additional fields. ### Method GET ### Endpoint /api/admin/stats ### Response #### Success Response (200) - **deletedImages** - Soft-deleted post count. - **thumbnailCount** - Count of indexed media-asset rows that store a non-empty thumbnail target. Independent of physical file existence. - **previewCount** - Count of indexed media-asset rows that store a non-empty preview target. Independent of physical file existence. - **storage.usingInMemoryDatabase** - Whether SQLite had to fall back to in-memory mode. - **libraryIndex.currentGalleryRoot** - Current configured gallery root. - **libraryIndex.previousGalleryRoot** - Prior configured gallery root when the root changed. - **libraryIndex.lastSuccessfulGalleryRoot** - Gallery root from the last completed successful scan. - **libraryIndex.legacyDerivativeMigrationPending** - Whether older mirrored derivatives still need a manual migration scan. - **libraryIndex.pendingDerivativeMigrationRows** - Count of indexed rows still pending legacy derivative migration checks. - **excludedFolders** - Env-backed, custom, and effective exclusion rules. - **deletionRecovery** - Failed permanent-deletion recovery count and admin-safe journal details. A failed journal remains quarantined and does not stop the server or scans. - **lastScan** - Last completed scan run. - **preferences.treatStoriesAsFolders** - Same as in GET /api/status. - **storiesMigration** - Same as in GET /api/status. ``` -------------------------------- ### POST /api/admin/rescan Source: https://github.com/foldergram/foldergram/blob/main/docs/api.md Runs a manual scan against the current library and then starts the development watcher. Optionally accepts a JSON body to control derivative repair behavior. ```APIDOC ## POST /api/admin/rescan ### Description Runs a manual scan against the current library and then starts the development watcher. ### Method POST ### Endpoint /api/admin/rescan ### Parameters #### Request Body - **repairDerivatives** (boolean) - Optional - Defaults to true. Set to false to skip ordinary unchanged derivative verification. ### Response #### Success Response (200) - **ok** (boolean) - Indicates success. - **lastScan** (object) - Details of the last scan. - **id** (integer) - Scan ID. - **status** (string) - Status of the scan (e.g., "completed", "completed_with_errors"). - **scanned_files** (integer) - Number of files scanned. ### Request Example ```json { "repairDerivatives": false } ``` #### Response Example ```json { "ok": true, "lastScan": { "id": 7, "status": "completed", "scanned_files": 120 } } ``` ### Errors - **400** - Invalid JSON or non-boolean repairDerivatives value. - **403** - Viewer sessions. - **409** - Library rebuild required when gallery root changed. - **500** - Scan failures surfaced from the scanner. ``` -------------------------------- ### Excluded folder example: .nofoldergram marker Source: https://github.com/foldergram/foldergram/blob/main/README.md Shows a gallery tree where Archive is excluded by an empty .nofoldergram file and Trips is indexed. The marker filename is fixed and contents are ignored. ```text gallery/ Trips/ photo.jpg Archive/ .nofoldergram old-photo.jpg Nested/ another-photo.jpg ``` -------------------------------- ### GET /api/trash/images Source: https://github.com/foldergram/foldergram/blob/main/docs/api.md Returns a paginated list of trashed images. This route is read-only and admin-only. ```APIDOC ## GET /api/trash/images ### Description Returns a paginated list of trashed images. This route is read-only and admin-only. ### Method GET ### Endpoint /api/trash/images ### Parameters #### Query Parameters - **page** (integer) - Optional - Default: 1 - **limit** (integer) - Optional - Default: 24 ### Response #### Success Response (200) ```json { "items": [], "page": 1, "limit": 24, "total": 0, "hasMore": false } ``` Each trash item uses the normal feed-item shape plus `trashedAt`. ``` -------------------------------- ### GET /api/scan-progress Source: https://github.com/foldergram/foldergram/blob/main/docs/api.md Returns the standalone viewer-safe scan payload used for lightweight polling. Access rules match GET /api/status: admin and viewer sessions can read it when access protection is enabled, and anonymous visitors can also read it when viewer_access_mode=public. ```APIDOC ## GET /api/scan-progress ### Description Returns the standalone viewer-safe scan payload used for lightweight polling. Access rules match GET /api/status: admin and viewer sessions can read it when access protection is enabled, and anonymous visitors can also read it when viewer_access_mode=public. ### Method GET ### Endpoint /api/scan-progress ### Response #### Success Response (200) - **isScanning** (boolean) - True for active local work, including pausing, paused, and cancelling. - **phase** (string) - `idle`, `migration`, `discovery`, or `derivatives`. - **operation.state** (string) - Lifecycle state for the active or most recent operation in this server process. - **scanReason** (string) - Current trigger such as startup, manual rescan, index rebuild, or thumbnail rebuild. - **currentPhaseMessage** (string) - Short phase summary for the UI. - **currentOperation** (string) - Current action label such as derivative repair, derivative move, metadata discovery, or derivative generation. - **migrationTotalRows** (number) - Progress through legacy derivative migration checks. - **processedMigrationRows** (number) - Progress through legacy derivative migration checks. - **migratedDerivativeFiles** (number) - Migration counters for moved assets. - **repairedDerivativeFiles** (number) - Migration counters for repaired assets. - **missingDerivativeFiles** (number) - Migration counters for missing assets. - **backfilledAssetKeys** (number) - Migration counters for backfilled assets. - **discoveredFolders** (number) - Folder discovery counters. - **processedFolders** (number) - Folder discovery counters. - **discoveredImages** (number) - Indexed-post discovery counters. - **processedImages** (number) - Indexed-post discovery counters. - **queuedDerivativeJobs** (number) - Derivative job counters once the queue is known. - **processedDerivativeJobs** (number) - Derivative job counters once the queue is known. - **generatedThumbnails** (number) - Completed derivative outputs in the current run. - **generatedPreviews** (number) - Completed derivative outputs in the current run. - **currentFolder** (null) - Always `null` in this viewer-safe route. - **currentFile** (null) - Always `null` in this viewer-safe route. - **lastCompletedScan** (object) - Latest completed scan summary with `error_text` forced to `null`. Runs can be `completed`, `completed_with_errors`, `failed`, `skipped_unavailable`, or `cancelled`. ### Notes - Discovery remains open-ended while folders and media are still being found, so clients should treat that phase as indeterminate even though the counters continue to advance. - Migration and derivative phases expose determinate totals once the work queue is known. ``` -------------------------------- ### GET /api/feed/moments Source: https://github.com/foldergram/foldergram/blob/main/docs/api.md Returns the current Home Moments or Highlights definition. The response can be either 'moments' or 'highlights'. ```APIDOC ## GET /api/feed/moments ### Description Returns the current Home Moments or Highlights definition. The response can be either 'moments' or 'highlights'. ### Method GET ### Endpoint /api/feed/moments ### Response #### Success Response (200) - **railKind** (string) - The kind of rail: `moments` or `highlights`. - **railTitle** (string) - Title of the rail. - **railDescription** (string) - Description of the rail. - **railSingularLabel** (string) - Singular label for the rail items. - **items** (array) - List of capsule items. Each capsule item includes: - **id** (string) - Identifier of the capsule. - **title** (string) - Title of the capsule. - **subtitle** (string) - Subtitle of the capsule. - **dateContext** (string) - Date context of the capsule. - **imageCount** (integer) - Number of images in the capsule. - **coverImage** (string) - URL or reference to the cover image. Date-driven Moment capsules also include **momentDate** (object) - Server-selected calendar data for localization. Possible shapes: - `{"type":"on-this-day","date":{"year":2026,"month":5,"day":31}}` - `{"type":"this-week-previous-years","startDate":{"year":2026,"month":5,"day":24},"endDate":{"year":2026,"month":6,"day":7}}` - `{"type":"from-last-year","referenceDate":{"year":2025,"month":5,"day":31},"startDate":{"year":2025,"month":4,"day":16},"endDate":{"year":2025,"month":7,"day":15}}` Highlight capsules omit `momentDate`. #### Response Example ```json { "railKind": "moments", "railTitle": "Moments", "railDescription": "Memory capsules shaped by real capture dates from your library.", "railSingularLabel": "Moment", "items": [] } ``` ``` -------------------------------- ### GET /api/share/posts/:id Source: https://github.com/foldergram/foldergram/blob/main/docs/api.md Retrieves a shareable version of a post. ```APIDOC ## GET /api/share/posts/:id ### Description Retrieves a shareable version of a post. ### Method GET ### Endpoint /api/share/posts/:id ### Parameters #### Path Parameters - **id** (string) - Required - The post ID. ### Response #### Success Response (200) - **post** (object) - The shareable post object. ``` -------------------------------- ### GET /api/folders/:slug/images Source: https://github.com/foldergram/foldergram/blob/main/docs/api.md Returns a paginated list of images (or videos) in a folder, along with folder summary information. ```APIDOC ## GET /api/folders/:slug/images ### Description Returns a paginated list of images (or videos) in a folder, along with folder summary information. ### Method GET ### Endpoint /api/folders/:slug/images ### Parameters #### Path Parameters - **slug** (string) - Required - The folder slug. #### Query Parameters - **page** (integer) - Optional - Default: `1`. Minimum `1`. - **limit** (integer) - Optional - Default: `24`. Minimum `1`, maximum `60`. - **mediaType** (string) - Optional - Can be `image` or `video`. Optional folder filter. ### Response #### Success Response (200) - **folder** (object) - Folder summary. - **items** (array) - List of media items. - **page** (integer) - Current page number. - **limit** (integer) - Page size. - **total** (integer) - Total matching items. - **hasMore** (boolean) - Whether more pages exist. #### Response Example ```json { "folder": { "id": 1, "slug": "oslo", "name": "oslo", "description": null, "folderPath": "trips/oslo", "breadcrumb": "trips", "imageCount": 12, "videoCount": 3, "latestImageMtimeMs": 1700000000000, "hasAvatarStory": false, "avatarImageId": 42, "avatarUrl": "/thumbnails/ab/abcd1234ef567890abcd1234ef567890.webp?v=4" }, "items": [], "page": 1, "limit": 24, "total": 12, "hasMore": false } ``` ### Errors - `404` with `{"message":"Folder not found"}` ### Notes - Results follow the current app-wide default folder image order. - That same order is reused by detail-view previous/next navigation within a folder. ``` -------------------------------- ### GET /api/places/:slug/images Source: https://github.com/foldergram/foldergram/blob/main/docs/api.md Returns a paginated list of images for a place, with optional media type filtering. ```APIDOC ## [GET] /api/places/:slug/images ### Description Returns a paginated list of images for a place, with optional media type filtering. ### Method GET ### Endpoint /api/places/:slug/images ### Query Parameters - `page` (integer) - Optional - Default `1`. Minimum `1`. - `limit` (integer) - Optional - Default `24`. Minimum `1`, maximum `60`. - `mediaType` (`image | video`) - Optional - Place filter. ### Response #### Success Response (200) ```json { "place": { "id": 1, "slug": "oslo-norway", "name": "Oslo", "kind": "city", "isApproximate": false, "latitude": 59.9139, "longitude": 10.7522, "cityName": "Oslo", "admin1Name": "Oslo", "countryName": "Norway", "countryCode": "NO", "description": null, "postCount": 18 }, "items": [], "page": 1, "limit": 24, "total": 18, "hasMore": false } ``` ### Errors - `404` with `{"message":"Place not found"}` ``` -------------------------------- ### Example of a folder structure that will not be indexed Source: https://github.com/foldergram/foldergram/blob/main/docs/troubleshooting.md Shows a gallery layout that Foldergram will not index because files directly inside GALLERY_ROOT are ignored and the oslo folder contains no supported media directly. ```text gallery/ loose-file.jpg trips/ oslo/ notes.txt ``` -------------------------------- ### GET /api/status Source: https://github.com/foldergram/foldergram/blob/main/docs/api.md Returns viewer-safe operational state for the shell. Accessible to admin and viewer sessions, and anonymous visitors when viewer_access_mode=public. ```APIDOC ## GET /api/status ### Description Returns viewer-safe operational state for the shell. Accessible to admin and viewer sessions, and anonymous visitors when viewer_access_mode=public. ### Method GET ### Endpoint /api/status ### Response #### Success Response (200) - **folders** (array) - Active indexed folders. - **indexedImages** (integer) - Historical alias for `indexedPosts`, including single-video and Carousel posts. - **indexedPosts** (integer) - Active visible posts. Each Carousel counts as one post. - **indexedMediaAssets** (integer) - Active visible physical media assets, including every Carousel item. - **indexedCarousels** (integer) - Active visible Carousel posts. - **indexedVideos** (integer) - Active visible single-video posts. Videos inside multi-item Carousels are excluded. - **scan** (object) - Viewer-safe live scan progress snapshot. Same shape as `GET /api/scan-progress`, with `currentFolder` and `currentFile` redacted and `lastCompletedScan.error_text` forced to `null`. Scan-report paths never appear here. - **storage** (object) - Availability with a generic unavailable message only. - **libraryIndex** (object) - Rebuild requirement plus ignored root-media count. Gallery-root paths are omitted. - **preferences.defaultLocale** (string) - Saved app-wide default locale when configured. Browsers can still keep their own local override. - **preferences.defaultHomeFeedMode** (string) - Current app-wide default home feed mode. - **preferences.defaultReelsFeedMode** (string) - Current app-wide default reels mode used when `/reels` opens. - **preferences.defaultFolderImageOrder** (string) - Current app-wide default order used for folder grids and folder detail navigation. - **preferences.treatStoriesAsFolders** (boolean) - Whether folders literally named `stories` are treated as ordinary app folders instead of reserved story sources. - **preferences.treatCarouselsAsFolders** (boolean) - Whether folders literally named `carousels` are treated as ordinary app folders instead of reserved carousel sources. - **storiesMigration** (object) - Migration hint with `hasLegacyStoriesCandidates` and `decisionPending`. - **carouselsMigration** (object) - Carousel migration state with `hasLegacyCarouselsCandidates`, `decisionPending`, and `reconciliationPending`. The last field remains true until a successful full scan applies the saved Carousel folder mode. ``` -------------------------------- ### GET /api/reels Source: https://github.com/foldergram/foldergram/blob/main/docs/api.md Retrieves a paginated list of video reels. Supports various modes and cursor-based pagination. ```APIDOC ## GET /api/reels ### Description Retrieves a paginated list of video reels. Supports various modes and cursor-based pagination. ### Method GET ### Endpoint /api/reels ### Parameters #### Query Parameters - **page** (integer) - Optional - Default: `1`. Minimum `1`. - **limit** (integer) - Optional - Default: `24`. Minimum `1`, maximum `60`. The current client helper requests `6` per page. - **mode** (`recommended | recent | random`) - Optional - Default: `recommended`. Reels queue mode. - **seed** (integer) - Optional - Optional seed used to keep `recommended` and `random` queues stable while paging. If omitted, the server uses a UTC-day default seed. When continuing a cursor without a seed, the cursor's seed is reused. Changing the seed starts a new session queue. - **lastFolder** (string) - Optional - Optional recent-navigation hint used by `recommended`. - **recentFolders** (comma-separated string) - Optional - Optional recent-navigation hints used by `recommended`. - **cursor** (string) - Optional - Opaque cursor returned by the previous page as `nextCursor`. When supplied, continue from that cursor and keep `mode`, `seed`, and recommendation hints unchanged. ### Response #### Success Response (200) - **mode** (string) - The mode of the reels queue. - **items** (array) - List of video items. - **page** (integer) - Current page number. - **limit** (integer) - Number of items per page. - **total** (integer) - Total number of visible videos (for `recent` and `random`); for `recommended`, total describes the bounded session queue. - **hasMore** (boolean) - Whether another page is available. - **nextCursor** (string|null) - Opaque cursor for the next page, or `null` if no more pages. #### Response Example ```json { "mode": "recommended", "items": [], "page": 1, "limit": 6, "total": 0, "hasMore": false, "nextCursor": null } ``` ``` -------------------------------- ### GET /api/auth/status Source: https://github.com/foldergram/foldergram/blob/main/docs/api.md Returns the current authentication status. Accessible without an authenticated session. ```APIDOC ## GET /api/auth/status ### Description Returns the current authentication status. Accessible without an authenticated session. ### Method GET ### Endpoint /api/auth/status ### Response #### Success Response (200) No response body documented. ``` -------------------------------- ### GET /api/places Source: https://github.com/foldergram/foldergram/blob/main/docs/api.md Returns a list of place detail summaries. Each item includes id, slug, name, kind, isApproximate, latitude, longitude, cityName, admin1Name, countryName, countryCode, description, and postCount. ```APIDOC ## [GET] /api/places ### Description Returns a list of place detail summaries. Each item includes id, slug, name, kind, isApproximate, latitude, longitude, cityName, admin1Name, countryName, countryCode, description, and postCount. ### Method GET ### Endpoint /api/places ### Response #### Success Response (200) ```json { "items": [] } ``` Each item is a place detail summary with: - `id` - `slug` - `name` - `kind` - `isApproximate` - `latitude` - `longitude` - `cityName` - `admin1Name` - `countryName` - `countryCode` - `description` - `postCount` ``` -------------------------------- ### GET /api/originals/:id Source: https://github.com/foldergram/foldergram/blob/main/docs/api.md Serves original media files. Uses a revalidation-friendly cache policy and supports range requests. ```APIDOC ## GET /api/originals/:id ### Description Serves original media files. Uses a revalidation-friendly cache policy and supports range requests. ### Method GET ### Endpoint /api/originals/:id ### Parameters #### Path Parameters - **id** (string) - Required - The image ID. ### Response #### Success Response (200) - **ETag** (string) - Entity tag for revalidation. - **Last-Modified** (string) - Last modification date. - **Accept-Ranges** (string) - Indicates support for range requests. ``` -------------------------------- ### GET /api/share/images/:id/... Source: https://github.com/foldergram/foldergram/blob/main/docs/api.md Serves folder-share media. Always uses private, no-store cache policy. ```APIDOC ## GET /api/share/images/:id/... ### Description Serves folder-share media. Always uses private, no-store cache policy. ### Method GET ### Endpoint /api/share/images/:id/... ### Parameters #### Path Parameters - **id** (string) - Required - The image ID. ### Response #### Success Response (200) No response body documented. ``` -------------------------------- ### GET /api/share/images/:id/preview Source: https://github.com/foldergram/foldergram/blob/main/docs/api.md Serves or lazily generates the preview for one physical media asset after checking its folder grant. The ID is an `images.id`, including for Carousel slides. Folder-share visitors do not receive ordinary original URLs, so this route can create a preview on authorized first access even when normal playback uses the original. ```APIDOC ## [GET] /api/share/images/:id/preview ### Description Serves or lazily generates the preview for one physical media asset after checking its folder grant. The ID is an `images.id`, including for Carousel slides. Folder-share visitors do not receive ordinary original URLs, so this route can create a preview on authorized first access even when normal playback uses the original. ### Method GET ### Endpoint /api/share/images/:id/preview ``` -------------------------------- ### GET /api/folders Source: https://github.com/foldergram/foldergram/blob/main/docs/api.md Returns a list of visible normal folders. Without parameters, returns the legacy response; with pagination parameters, returns a paginated directory response. ```APIDOC ## GET /api/folders ### Description Returns a list of visible normal folders. Without parameters, returns the legacy `{ "items": [...] }` response. With pagination parameters, returns a paginated directory response. ### Method GET ### Endpoint /api/folders ### Parameters #### Query Parameters - **page** (integer) - Optional - Default: `1`. Starts at 1. - **limit** (integer) - Optional - Default: `50`. Between 1 and 200. - **q** (string) - Optional - Default: empty. Up to 160 characters. Case-insensitive search across folder names, parent display names, slugs, breadcrumbs, and source paths. All whitespace-separated terms must match; `%`, `_`, and backslashes are literal characters. - **sort** (string) - Optional - Default: `recent-desc`. One of `recent-desc`, `images-desc`, `name-asc`, `name-desc`, or `path-asc`. - **pathPrefix** (string) - Optional - Default: absent. Literal, case-sensitive source-path prefix, up to 4,096 characters. Include a trailing `/` when requesting descendants of a folder. ### Response #### Success Response (200) - **items** (array) - List of folder summaries. - **page** (integer) - Current page number. - **limit** (integer) - Page size. - **total** (integer) - Total matching folders. - **hasMore** (boolean) - Whether more pages exist. #### Request Example ```json /api/folders?page=1&limit=50&q=summer&sort=name-asc ``` #### Response Example ```json { "items": [], "page": 1, "limit": 50, "total": 0, "hasMore": false } ``` ### Notes - `total` counts all matching folders, including those on later pages. - Every sort has stable path and ID tie-breakers. - Pages reflect the current index; a scan or mutation can move results between pages, so refresh the listing after changes. - Empty pages still return the matching total. - Invalid parameters return `400`. - The application loads up to 24 recent folder summaries for Home and sidebar recommendations. - Library and Explore folder searches use independent pages of 50. - Feed and Reels items include `folderAvatarUrl` and `folderHasAvatarStory`. - Each item is a folder summary with: `id`, `slug`, `name`, `description`, `folderPath`, `breadcrumb`, `imageCount`, `videoCount`, `latestImageMtimeMs`, `hasAvatarStory`, `avatarImageId`, `avatarUrl`. ``` -------------------------------- ### GET /api/collections Source: https://github.com/foldergram/foldergram/blob/main/docs/api.md Returns a list of shared collections. Available to admin and viewer sessions; anonymous sessions use browser-local collections. ```APIDOC ## GET /api/collections ### Description Returns a list of shared collections. ### Method GET ### Endpoint /api/collections ### Response #### Success Response (200) ```json { "items": [] } ``` Each item includes: - `id` - `slug` - `name` - `isDefault` - `itemCount` - `coverImage` - `previewImages` - `createdAt` - `updatedAt` ``` -------------------------------- ### GET /api/likes Source: https://github.com/foldergram/foldergram/blob/main/docs/api.md Returns a list of liked items ordered by like timestamp descending. Available to admin and viewer sessions; anonymous sessions use browser-local favorites. ```APIDOC ## GET /api/likes ### Description Returns a list of liked items ordered by like timestamp descending. ### Method GET ### Endpoint /api/likes ### Response #### Success Response (200) ```json { "items": [] } ``` ``` -------------------------------- ### Create first gallery folder Source: https://github.com/foldergram/foldergram/blob/main/README.md Creates the directory structure for the first indexed App Folder. ```bash mkdir -p data/gallery/example-album ``` -------------------------------- ### GET /api/feed/search Source: https://github.com/foldergram/foldergram/blob/main/docs/api.md Searches the feed and returns the same paginated mixed-media payload shape as GET /api/feed. ```APIDOC ## GET /api/feed/search ### Description Searches the feed and returns the same paginated mixed-media payload shape as GET /api/feed. ### Method GET ### Endpoint /api/feed/search ### Parameters #### Query Parameters - **q** (string) - Required - Search text. - **page** (integer) - Optional - Default `1`, minimum `1`. - **limit** (integer) - Optional - Default `24`, minimum `1`, maximum `60`. ### Response #### Success Response (200) Same shape as `GET /api/feed`. ``` -------------------------------- ### Download docker-compose.yml Source: https://github.com/foldergram/foldergram/blob/main/README.md Downloads the Compose file from the Foldergram GitHub repository using wget. ```bash wget -O docker-compose.yml https://raw.githubusercontent.com/foldergram/foldergram/main/docker-compose.yml ``` -------------------------------- ### Docker Compose environment configuration for Immich source Source: https://github.com/foldergram/foldergram/blob/main/docs/immich.md Configure Foldergram's Immich source via environment variables in Docker Compose. Use the Immich service hostname and internal port when sharing a Docker network. The key-file option takes precedence over IMMICH_API_KEY. Removing IMMICH_URL releases the source to Settings management. IMMICH_SYNC_MODE accepts folders, albums, or both; IMMICH_SYNC_INTERVAL_MINUTES=0 means manual. No roots and no albums imports nothing unless IMMICH_INCLUDE_UNFILED=true. IMMICH_ALLOW_ORIGINALS=true requires the key to have asset.download. Invalid or offline bootstrap does not prevent startup. ```yaml # Add to your Foldergram service and attach the appropriate shared Docker network. environment: IMMICH_URL: http://immich-server:2283 IMMICH_API_KEY_FILE: /run/secrets/immich_api_key IMMICH_SYNC_MODE: folders # folders, albums, both IMMICH_ROOTS: '[{"libraryId":"your-library-uuid","path":"/mnt/photos"}]' IMMICH_ALBUM_IDS: "" # comma-separated album UUIDs IMMICH_AUTO_SYNC: "true" IMMICH_SYNC_INTERVAL_MINUTES: "60" # 0 = manual secrets: - immich_api_key # At the Compose top level: # secrets: # immich_api_key: # file: ./secrets/immich_api_key ```