docs: improve install/requirements and install/docker-compose #13569
Conversation
|
Label error. Requires exactly 1 of: changelog:.*. Found: documentation |
github-actions
bot
added
the
documentation
docs/docs/install/docker-compose.mdx
Outdated
| docker compose pull && docker compose up -d | ||
| ``` | ||
|
|
||
| To clean up disk space, the old version's obsolete containers can be deleted with the following command, which deletes all stopped containers. As such, make sure to start Immich (with the previous command) before running it. |
There was a problem hiding this comment.
| To clean up disk space, the old version's obsolete containers can be deleted with the following command, which deletes all stopped containers. As such, make sure to start Immich (with the previous command) before running it. | |
| To clean up disk space, the old version's obsolete containers can be deleted with the following command, which deletes all unused container images. As such, make sure to start Immich (with the previous command) before running it. |
There was a problem hiding this comment.
Wasn’t aware of images vs containers but looks good, will merge.
There was a problem hiding this comment.
I believe this command can be run with the containers stopped so I deleted that second sentence as well.
There was a problem hiding this comment.
actually i tried running docker image prune with the containers stopped and i feel like docker compose up -d then redownloaded some stuff? unsure, needs checking
|
|
||
| :::note | ||
| Immich requires the command `docker compose` - the similarly named `docker-compose` is [deprecated](https://docs.docker.com/compose/migrate/) and is no longer compatible with Immich. | ||
| Immich requires the command `docker compose` (the plugin); the similarly named `docker-compose` (the standalone) is [deprecated](https://docs.docker.com/compose/migrate/) and is no longer compatible with Immich. |
There was a problem hiding this comment.
I think this plugin vs standalone talk is more confusing, not less
There was a problem hiding this comment.
For immich’s purposes strictly, it is; however, the Docker Compose installation docs that this page links specifically give the choice between installing Docker Desktop, the Compose plugin, or the Compose standalone.
There was a problem hiding this comment.
It gives the choice but also pretty clearly notes that the standalone is deprecated, so I don't think we need to repeat that here.
There was a problem hiding this comment.
That’s fair yeah; I just figured people might want to join the dots on which installation option corresponds to which command, as an explanation for why the old command doesn’t work. I did delete the reference to “v2” over “v1” since I could hardly find it on Docker’s website. But yeah, omitting those brackets is fine.
There was a problem hiding this comment.
I'd suggest replacing compatible with supported. New Synology nas systems use docker-compose and it seems to be running fine for me.
| - **OS**: Recommended Linux operating system (Ubuntu, Debian, etc). | ||
| - Windows is supported with [Docker Desktop on Windows](https://docs.docker.com/desktop/install/windows-install/) or [WSL 2](https://docs.docker.com/desktop/wsl/). | ||
| - macOS is supported with [Docker Desktop on Mac](https://docs.docker.com/desktop/install/mac-install/). | ||
| - **OS**: Linux is recommended, and Windows and macOS are supported: any version or distribution that Docker can be installed on (see above). |
There was a problem hiding this comment.
Not fond of this change, would prefer it how we had it.
There was a problem hiding this comment.
Could you elaborate please?
The purpose of this change is to move all Docker variant-selection info into the “Software” section. Not making this change would leave two copies of this info. Arguably, this remaining OS info could entirely be moved into “Software” as well.
docs/docs/install/docker-compose.mdx
Outdated
|
|
||
| ```bash title="Start the containers using docker compose command" | ||
| docker compose up -d | ||
| ``` | ||
|
|
||
| The `restart: always` entries in `docker-compose.yml` for each container mean they will always restart after system reboot or program crashes. |
There was a problem hiding this comment.
This isn't needed here (or really at all IMO, this is man docker stuff)
There was a problem hiding this comment.
The purpose of this line is to inform those of us who don’t use or care about Docker that the “compose up” command starts immich as a persistent service, which IMO is a worry that would cross the minds of users who aren’t culturally immersed in Linux to the point of intuitively expecting the behaviour.
The point isn’t to explain “restart: always” but rather to say “this command starts the container and ensures it automatically restarts”. I’ll reword it to make that clearer.
There was a problem hiding this comment.
A topic we find ourselves constantly trying to balance is how much basic information to include in our docs. We're documenting Immich, and so I don't think we should expect to be teaching people sysadmin basics. If someone is wondering about details of the restart behaviour, they can find answers to that in plenty of places already.
There was a problem hiding this comment.
I changed it earlier to something closer to what I intended:
This starts immich and ensures it automatically restarts after system reboots or crashes (thanks to the
restart: alwaysentries indocker-compose.yml).
The bracketed bit is more for curiosity and can be deleted cos it’s somewhat evident from the non-bracketed bit, if one also reads the yaml file.
But yeah I wouldn’t consider this teaching as much as explaining what that command actually does. On further thought, I recall seeing people forget the d flag, which is kind of a similar mistake – we’re trying to say the command starts the program as a service, so not blocking the console, but as a background thing that auto restarts. Basically that’s what I wanted.
There was a problem hiding this comment.
New sentence: I am feeling:
This starts immich as a background service, ensuring it restarts after system reboots or crashes.
Or with btw teaching:
This starts immich as a background service (per the -d flag), ensuring it restarts after system reboots or crashes (per the
restartfields indocker-compose.yml).
docs/docs/install/docker-compose.mdx
Outdated
| - Populate custom database information if necessary. | ||
|
|
||
| :::info Optional Features | ||
| You can make the required edits to `docker-compose.yml` to add external libraries or enable hardware acceleration now by following [their guides](#setting-up-optional-features) up to and including those edits. |
There was a problem hiding this comment.
| You can make the required edits to `docker-compose.yml` to add external libraries or enable hardware acceleration now by following [their guides](#setting-up-optional-features) up to and including those edits. | |
| You can edit `docker-compose.yml` to add external libraries or enable hardware acceleration now by following [their guides](#setting-up-optional-features). |
There was a problem hiding this comment.
I think this is a fair simplification; it’s just annoying that the optional guides don’t split apart the yaml file edits from the settings changes made to the running program, so users who follow this tip would have to flip-flop between the two pages.
|
📖 Documentation deployed to pr-13569.preview.immich.app |
|
Thanks for the review; I'll check it out tomo. |
|
I flushed all edits and so can open the PR up for formal review. BTW I force-pushed during the first review so there might be extra changes @mmomjian would like to peep (mostly moving some fine details (e.g. about pwgen) from quick-start into install/docker-compose. |
Another thing that crossed my mind as a potential change to add is that the order of these features is a bit weird; I'd swap External Libraries and Hardware Transcoding. |
|
Updated all my suggestions and am happy to stop working on this and allow whichever parts to be merged.
Turns out there’re no sidebar front-matter parameters in the whole features folder so I’ll let a different patch sort that out. The capitalisation of the Supported Formats page’s headings is also inconsistent with the other pages in that folder. |
Giving back changes that mostly would've helped me starting out with Immich:
The idea is to explain some of the basics of Docker (1, 4, 6) and Linux (5) as we go, and streamline out-of-order steps (2, 3, 7). Once I've looked over the compiled docs, I'll set this as ready for review and you can tell me which edits you fancy :).