diff --git a/docs/docs/FAQ.md b/docs/docs/FAQ.md index 8ba398587cfad..4b5a7c6b8721b 100644 --- a/docs/docs/FAQ.md +++ b/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. diff --git a/docs/docs/features/automatic-backup.md b/docs/docs/features/automatic-backup.md index 7e526d8886c08..c2889d5fba0ed 100644 --- a/docs/docs/features/automatic-backup.md +++ b/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. diff --git a/docs/docs/features/bulk-upload.md b/docs/docs/features/bulk-upload.md index 5fd97c73229f9..fa883210f7fd4 100644 --- a/docs/docs/features/bulk-upload.md +++ b/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 diff --git a/docs/docs/features/img/admin-jobs-exif.png b/docs/docs/features/img/admin-jobs-exif.png new file mode 100644 index 0000000000000..6c3f0bfefb1e9 Binary files /dev/null and b/docs/docs/features/img/admin-jobs-exif.png differ diff --git a/docs/docs/features/img/admin-jobs-objects.png b/docs/docs/features/img/admin-jobs-objects.png new file mode 100644 index 0000000000000..d7dd678f981e5 Binary files /dev/null and b/docs/docs/features/img/admin-jobs-objects.png differ diff --git a/docs/docs/features/img/admin-jobs-template.png b/docs/docs/features/img/admin-jobs-template.png new file mode 100644 index 0000000000000..b3fc087877460 Binary files /dev/null and b/docs/docs/features/img/admin-jobs-template.png differ diff --git a/docs/docs/features/img/admin-jobs-thumbnails.png b/docs/docs/features/img/admin-jobs-thumbnails.png new file mode 100644 index 0000000000000..a8cdc5df1bba3 Binary files /dev/null and b/docs/docs/features/img/admin-jobs-thumbnails.png differ diff --git a/docs/docs/features/img/oauth-settings.png b/docs/docs/features/img/oauth-settings.png new file mode 100644 index 0000000000000..9ab903e69959e Binary files /dev/null and b/docs/docs/features/img/oauth-settings.png differ diff --git a/docs/docs/features/img/reverse-geocoding-mobile1.png b/docs/docs/features/img/reverse-geocoding-mobile1.png new file mode 100644 index 0000000000000..54ffad3f962d5 Binary files /dev/null and b/docs/docs/features/img/reverse-geocoding-mobile1.png differ diff --git a/docs/docs/features/img/reverse-geocoding-mobile2.png b/docs/docs/features/img/reverse-geocoding-mobile2.png new file mode 100644 index 0000000000000..f6858c50c4c88 Binary files /dev/null and b/docs/docs/features/img/reverse-geocoding-mobile2.png differ diff --git a/docs/docs/features/img/user-change-password.png b/docs/docs/features/img/user-change-password.png new file mode 100644 index 0000000000000..66741168af692 Binary files /dev/null and b/docs/docs/features/img/user-change-password.png differ diff --git a/docs/docs/features/img/user-popup.png b/docs/docs/features/img/user-popup.png new file mode 100644 index 0000000000000..d12522836d341 Binary files /dev/null and b/docs/docs/features/img/user-popup.png differ diff --git a/docs/docs/features/img/user-profile.png b/docs/docs/features/img/user-profile.png new file mode 100644 index 0000000000000..bf7bc78865a4c Binary files /dev/null and b/docs/docs/features/img/user-profile.png differ diff --git a/docs/docs/features/jobs.md b/docs/docs/features/jobs.md new file mode 100644 index 0000000000000..013c122d1e123 --- /dev/null +++ b/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) diff --git a/docs/docs/features/mobile-app.mdx b/docs/docs/features/mobile-app.mdx index 16ad4284b6905..9a79ccf17d92a 100644 --- a/docs/docs/features/mobile-app.mdx +++ b/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'; diff --git a/docs/docs/features/oauth.md b/docs/docs/features/oauth.md index 13f046eb18e30..c84cea471ce9d 100644 --- a/docs/docs/features/oauth.md +++ b/docs/docs/features/oauth.md @@ -1,7 +1,3 @@ ---- -sidebar_position: 6 ---- - # OAuth Authentication 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). -| 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 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/ diff --git a/docs/docs/features/reverse-geocoding.md b/docs/docs/features/reverse-geocoding.md new file mode 100644 index 0000000000000..c186b7abcce68 --- /dev/null +++ b/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). + + + diff --git a/docs/docs/features/search.md b/docs/docs/features/search.md new file mode 100644 index 0000000000000..e6be3521af28f --- /dev/null +++ b/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). + + + diff --git a/docs/docs/features/server-commands.md b/docs/docs/features/server-commands.md index e357cf47f4b58..0a41099e3ade8 100644 --- a/docs/docs/features/server-commands.md +++ b/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: diff --git a/docs/docs/features/storage-template.mdx b/docs/docs/features/storage-template.mdx index 4460a769d451b..8f6547d09af54 100644 --- a/docs/docs/features/storage-template.mdx +++ b/docs/docs/features/storage-template.mdx @@ -1,7 +1,3 @@ ---- -sidebar_position: 5 ---- - import StorageTemplate from '../partials/_storage-template.md'; # Storage Template diff --git a/docs/docs/features/user-management.mdx b/docs/docs/features/user-management.mdx index d5c9f994c1aad..a3d977c06b999 100644 --- a/docs/docs/features/user-management.mdx +++ b/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'; diff --git a/docs/docs/features/user-settings.md b/docs/docs/features/user-settings.md new file mode 100644 index 0000000000000..fa1f784205363 --- /dev/null +++ b/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) +::: diff --git a/docs/docs/guides/_category_.json b/docs/docs/guides/_category_.json new file mode 100644 index 0000000000000..951513baa878d --- /dev/null +++ b/docs/docs/guides/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Guides", + "position": 5 +} diff --git a/docs/docs/guides/docker-help.md b/docs/docs/guides/docker-help.md new file mode 100644 index 0000000000000..a2e633efd6a4f --- /dev/null +++ b/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 # 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 ` command will stream new logs, instead of immediately exiting, which is often useful for debugging. +:::