chore(docs): FAQs, geocoding, jobs, search, and user settings (#1160)

docs/docs/FAQ.md

@@ -20,6 +20,41 @@ Immich doesn't have the mechanism to sync an existing directory with the server.
 
 The initial approach of Immich is to become a backup tool, primarily for mobile device usage. Thus, all the assets must be uploaded from the mobile client. The app was architectured to perform that job well.
 
+### What happens to existing files after I choose a new [Storage Template](/docs/features/storage-template.mdx)?
+
+Template changes will only apply to new assets. To retroactively apply the template to previously uploaded assets, run the Storage Migration Job, available on the [Jobs](/docs/features/jobs.md) page.
+
+### Why is object detection not very good?
+
+The model we used for machine learning is a prebuilt model, so the accuracy is not very good. It will hopefully be replaced with a better solution in the future.
+
+### How can I see Immich logs?
+
+Most Immich components are typically deployed using docker. To see logs for deployed docker containers, you can use the [Docker CLI](https://docs.docker.com/engine/reference/commandline/cli/), specifically the `docker logs` command. For examples, see [Docker Help](/docs/guides/docker-help.md)
+
+### How can I run Immich as a non-root user?
+
+1. Set the `PUID`/`PGID` environment variables (in `.env`).
+2. Set the corresponding `user` argument in `docker-compose` for each service.
+3. Add an additional volume to `immich-microservices` that mounts internally to `/usr/src/app/.reverse-geocoding-dump`.
+
+The non-root user/group needs will need read/write access to the volume mounts, including `UPLOAD_LOCATION`.
+
 ### How can I reset the admin password?
 
 The admin password can be reset by running the [reset-admin-password](/docs/features/server-commands.md) command on the immich-server.
+
+### How can I **purge** data from Immich?
+
+Data for Immich comes in two forms:
+
+1. **Metadata** stored in a postgres database, persisted via the `pg_data` volume
+2. **Files** (originals, thumbs, profile, etc.), stored in the `UPLOAD_LOCATION` folder.
+
+To remove the **Metadata** you can stop Immich and delete the volume.
+
+```bash title="Remove Immich (containers and volumes)"
+docker-compose down -v
+```
+
+After removing the the containers and volumes, the **Files** can be cleaned up (if necessary) from the `UPLOAD_LOCATION` by simply deleting an unwanted files or folders.

docs/docs/features/automatic-backup.md

@@ -1,7 +1,3 @@
----
-sidebar_position: 2
----
-
 # Automatic Backup
 
 A guide on how the foreground and background automatic backup works.

docs/docs/features/bulk-upload.md

@@ -1,7 +1,3 @@
----
-sidebar_position: 3
----
-
 # Bulk Upload (Using the CLI)
 
 You can use the CLI to upload an existing gallery to the Immich server

docs/docs/features/jobs.md

@@ -0,0 +1,23 @@
+# Jobs
+
+Several Immich functionalities are implemented as jobs, which run in the background. To view the status of a job navigate to the Administration Screen, and then the `Jobs` page.
+
+
+## Generate Thumbnails
+
+![Generate Thumbnails](./img/admin-jobs-thumbnails.png)
+
+
+## Extract Exif
+
+![Extract Exif](./img/admin-jobs-exif.png)
+
+## Detect Objects
+
+![Detect Objects](./img/admin-jobs-objects.png)
+
+## Storage Migration
+
+This job can be run after changing the [Storage Template](/docs/features/storage-template.mdx), in order to apply the change to the existing library.
+
+![Storage Migration](./img/admin-jobs-template.png)

docs/docs/features/mobile-app.mdx

@@ -1,7 +1,3 @@
----
-sidebar_position: 1
----
-
 import MobileAppDownload from '../partials/_mobile-app-download.md';
 import MobileAppLogin from '../partials/_mobile-app-login.md';
 import MobileAppBackup from '../partials/_mobile-app-login.md';

docs/docs/features/oauth.md

@@ -1,7 +1,3 @@
----
-sidebar_position: 6
----
-
 # OAuth Authentication
 
 This page contains details about using OAuth in Immich.
@@ -45,14 +41,14 @@ You **MUST** include `app.immich:/` as the redirect URI for iOS and Android mobi
 Once you have a new OAuth client application configured, Immich can be configured using the Administration Settings page, available on the web (Administration -> Settings).
 
 | Setting       | Type    | Default              | Description                                                               |
-| ------------------- | ------- | -------------------- | ------------------------------------------------------------------------- |
+| ------------- | ------- | -------------------- | ------------------------------------------------------------------------- |
-| OAuth enabled       | boolean | false                | Enable/disable OAuth2                                                     |
+| Enabled       | boolean | false                | Enable/disable OAuth                                                     |
-| OAuth issuer URL    | URL     | (required)           | Required. Self-discovery URL for client (from previous step)              |
+| Issuer URL    | URL     | (required)           | Required. Self-discovery URL for client (from previous step)              |
-| OAuth client ID     | string  | (required)           | Required. Client ID (from previous step)                                  |
+| Client ID     | string  | (required)           | Required. Client ID (from previous step)                                  |
-| OAuth client secret | string  | (required)           | Required. Client Secret (previous step)                                   |
+| Client secret | string  | (required)           | Required. Client Secret (previous step)                                   |
-| OAuth scope         | string  | openid email profile | Full list of scopes to send with the request (space delimited)            |
+| Scope         | string  | openid email profile | Full list of scopes to send with the request (space delimited)            |
-| OAuth button text   | string  | Login with OAuth     | Text for the OAuth button on the web                                      |
+| Button text   | string  | Login with OAuth     | Text for the OAuth button on the web                                      |
-| OAuth auto register | boolean | true                 | When true, will automatically register a user the first time they sign in |
+| Auto register | boolean | true                 | When true, will automatically register a user the first time they sign in |
 
 :::info
 The Issuer URL should look something like the following, and return a valid json document.
@@ -63,4 +59,8 @@ The Issuer URL should look something like the following, and return a valid json
 The `.well-known/openid-configuration` part of the url is optional and will be automatically added during discovery.
 :::
 
+Here's an example of OAuth configured for Authentik:
+
+![OAuth Settings](./img/oauth-settings.png)
+
 [oidc]: https://openid.net/connect/

docs/docs/features/reverse-geocoding.md

@@ -0,0 +1,14 @@
+# Reverse Geocoding
+
+Immich supports [Reverse Geocoding](https://en.wikipedia.org/wiki/Reverse_geocoding) using data from the [GeoNames](https://www.geonames.org/) geographical database.
+
+## Extraction
+
+During Exif Extraction, assets with latitudes and longitudes are reverse geocoded to determine their City, State, and Country. 
+
+## Usage
+
+Data from a reverse geocode is displayed in the image details, and used in [Search](/docs/features/search.md).
+
+<img src={require('./img/reverse-geocoding-mobile1.png').default} width='33%' title='Reverse Geocoding' />
+<img src={require('./img/reverse-geocoding-mobile2.png').default} width='33%' title='Reverse Geocoding' />

docs/docs/features/search.md

@@ -0,0 +1,16 @@
+# Search
+
+:::warning Work In Progress
+Search is work-in-progress and subject to change. Stay tuned!
+:::
+
+## Search by Place
+
+:::info
+Searching is currently only implemented in the [Mobile App](/docs/features/mobile-app.mdx)
+:::
+
+Searching by the name of a city, state, or country is possible for assets with geolocation data and successful [Reverse Geocoding](/docs/features/reverse-geocoding.md).
+
+<img src={require('./img/reverse-geocoding-mobile1.png').default} width='33%' title='Reverse Geocoding' />
+<img src={require('./img/reverse-geocoding-mobile2.png').default} width='33%' title='Reverse Geocoding' />

docs/docs/features/server-commands.md

@@ -1,7 +1,3 @@
----
-sidebar_position: 7
----
-
 # Server Commands
 
 The `immich-server` docker image comes preinstalled with an administrative CLI that supports the following commands:

docs/docs/features/storage-template.mdx

@@ -1,7 +1,3 @@
----
-sidebar_position: 5
----
-
 import StorageTemplate from '../partials/_storage-template.md';
 
 # Storage Template

docs/docs/features/user-management.mdx

@@ -1,7 +1,3 @@
----
-sidebar_position: 4
----
-
 import RegisterAdminUser from '../partials/_register-admin.md';
 import UserCreate from '../partials/_user-create.md';
 

docs/docs/features/user-settings.md

@@ -0,0 +1,23 @@
+# User Settings
+
+![User Modal](./img/user-popup.png)
+
+## User Profile
+
+View your User ID and email, and update your first and last name.
+
+![User Profile](./img/user-profile.png)
+
+## Change Password
+
+Users can change their own passwords. 
+
+![Change Password](./img/user-change-password.png)
+
+:::tip Reset Password
+The admin can reset a password through the [User Management](/docs/features/user-management.mdx) screen.
+:::
+
+:::tip Reset Admin Password
+The admin password can be reset using a [Server Command](/docs/features/server-commands.md)
+:::

docs/docs/guides/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Guides",
+  "position": 5
+}

docs/docs/guides/docker-help.md

@@ -0,0 +1,23 @@
+---
+sidebar_position: 1
+---
+
+# Docker Help
+
+## Logs
+
+```bash title="Log Examples"
+docker ps                         # see a list of running containers
+docker ps -a                      # see a list of running and stopped containers
+docker logs <id or name>          # see the logs for a specific container (by id or name)
+
+docker logs immich_server
+docker logs immich_microservices
+docker logs immich_machine_learning
+docker logs immich_web
+docker logs immich_proxy
+```
+
+:::tip Follow a log
+Adding `--follow` to a `docker logs <id or name>` command will stream new logs, instead of immediately exiting, which is often useful for debugging.
+:::