Selaa lähdekoodia

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

Jason Rasmussen 2 vuotta sitten
vanhempi
commit
da9c961fca

+ 35 - 0
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.
 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?
 ### 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.
 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.

+ 0 - 4
docs/docs/features/automatic-backup.md

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

+ 0 - 4
docs/docs/features/bulk-upload.md

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

BIN
docs/docs/features/img/admin-jobs-exif.png


BIN
docs/docs/features/img/admin-jobs-objects.png


BIN
docs/docs/features/img/admin-jobs-template.png


BIN
docs/docs/features/img/admin-jobs-thumbnails.png


BIN
docs/docs/features/img/oauth-settings.png


BIN
docs/docs/features/img/reverse-geocoding-mobile1.png


BIN
docs/docs/features/img/reverse-geocoding-mobile2.png


BIN
docs/docs/features/img/user-change-password.png


BIN
docs/docs/features/img/user-popup.png


BIN
docs/docs/features/img/user-profile.png


+ 23 - 0
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)

+ 0 - 4
docs/docs/features/mobile-app.mdx

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

+ 13 - 13
docs/docs/features/oauth.md

@@ -1,7 +1,3 @@
----
-sidebar_position: 6
----
-
 # OAuth Authentication
 # OAuth Authentication
 
 
 This page contains details about using OAuth in Immich.
 This page contains details about using OAuth in Immich.
@@ -44,15 +40,15 @@ 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).
 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                                                     |
-| OAuth issuer URL    | URL     | (required)           | Required. Self-discovery URL for client (from previous step)              |
-| OAuth client ID     | string  | (required)           | Required. Client ID (from previous step)                                  |
-| OAuth 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)            |
-| OAuth 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 |
+| Setting       | Type    | Default              | Description                                                               |
+| ------------- | ------- | -------------------- | ------------------------------------------------------------------------- |
+| Enabled       | boolean | false                | Enable/disable OAuth                                                     |
+| Issuer URL    | URL     | (required)           | Required. Self-discovery URL for client (from previous step)              |
+| Client ID     | string  | (required)           | Required. Client ID (from previous step)                                  |
+| Client secret | string  | (required)           | Required. Client Secret (previous step)                                   |
+| Scope         | string  | openid email profile | Full list of scopes to send with the request (space delimited)            |
+| Button text   | string  | Login with OAuth     | Text for the OAuth button on the web                                      |
+| Auto register | boolean | true                 | When true, will automatically register a user the first time they sign in |
 
 
 :::info
 :::info
 The Issuer URL should look something like the following, and return a valid json document.
 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.
 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/
 [oidc]: https://openid.net/connect/

+ 14 - 0
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' />

+ 16 - 0
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' />

+ 0 - 4
docs/docs/features/server-commands.md

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

+ 0 - 4
docs/docs/features/storage-template.mdx

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

+ 0 - 4
docs/docs/features/user-management.mdx

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

+ 23 - 0
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)
+:::

+ 4 - 0
docs/docs/guides/_category_.json

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

+ 23 - 0
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.
+:::