Skip to content

Commit

Permalink
feat: refactor docker installation guide (#397)
Browse files Browse the repository at this point in the history
  • Loading branch information
@Mmx233
Mmx233 authored Jan 10, 2025
1 parent d41312f commit 00aa292
Show file tree
Hide file tree
Showing 2 changed files with 153 additions and 339 deletions.
243 changes: 76 additions & 167 deletions docs/guide/install/docker.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,182 +18,125 @@ star: true

# Use Docker

## See the admin's info:
## Install

#### Lower than v3.25.0

```bash
docker exec -it alist ./alist admin
```

#### Higher than v3.25.0

Versions above 3.25.0 change the password to an encrypted hash value, and the password cannot be calculated directly. If the password is forgotten, it can only be re-**`randomly generated`** or **`manually set`**

```bash
# Randomly generate a password
docker exec -it alist ./alist admin random
# Manually set a password, `NEW_PASSWORD` refers to the password you need to set
docker exec -it alist ./alist admin set NEW_PASSWORD
```

## **Release version**

#### **docker-cli**
#### **docker cli**

```bash
docker run -d --restart=unless-stopped -v /etc/alist:/opt/alist/data -p 5244:5244 -e PUID=0 -e PGID=0 -e UMASK=022 --name="alist" xhofe/alist:latest
```

#### **docker-compose**

```bash
mkdir /etc/alist
cd /etc/alist
wget https://alist.nn.ci/docker-compose.yml
docker-compose up -d
```

**Alternatively, you can manually create a `docker-compose.yml` file with the following content.**
#### **docker compose**

```yaml
version: '3.3'
services:
alist:
image: 'xhofe/alist:latest'
container_name: alist
volumes:
- '/etc/alist:/opt/alist/data'
ports:
- '5244:5244'
environment:
- PUID=0
- PGID=0
- UMASK=022
restart: unless-stopped
alist:
image: 'xhofe/alist:beta'
container_name: alist
volumes:
- '/etc/alist:/opt/alist/data'
ports:
- '5244:5244'
environment:
- PUID=0
- PGID=0
- UMASK=022
restart: unless-stopped
```
After the service runs, the default time zone for the container is UTC time zone. If you want to specify the time zone for the container to run, you can achieve this by passing this variable:`-e "TZ=Asia/Shanghai"`。

### **Offline download with aria2**
If you want to use aria2 to offline download, we recommend you to use this [image](https://hub.docker.com/r/xhofe/alist-aria2), which carries a pre-installed aria2.
#### **Env**
### **Dev version**
Just for amd64/arm64. Not recommended, this may can't work properly.
| Name | Default | Desc |
|:------------|:--------|----------------------------------------------------------------------------------------------------------------------------|
| `PUID` | `0` | User UID |
| `PGID` | `0` | User GID |
| `UMASK` | `022` | https://en.wikipedia.org/wiki/Umask |
| `RUN_ARIA2` | | Whether to run ARIA2 concurrently, default is `true` if aria2 is pre-installed, otherwise it is `false`. |
| `TZ` | | Default is the UTC time zone. If you want to specify a time zone, you can set this variable, for example: `Asia/Shanghai`. |

#### **docker-cli**
#### **Image Versions**

```bash
docker run -d --restart=unless-stopped -v /etc/alist:/opt/alist/data -p 5244:5244 -e PUID=0 -e PGID=0 -e UMASK=022 --name="alist" xhofe/alist:beta
```
Stable version: `xhofe/alist:latest` or specify a specific version, such as `xhofe/alist:v3.41.0` `xhofe/alist:v3.40.0`

#### **docker-compose**
Latest image version, please refer to https://hub.docker.com/r/xhofe/alist/tags

```yaml
version: '3.3'
services:
alist:
image: 'xhofe/alist:beta'
container_name: alist
volumes:
- '/etc/alist:/opt/alist/data'
ports:
- '5244:5244'
environment:
- PUID=0
- PGID=0
- UMASK=022
restart: unless-stopped
```
Dev version: `xhofe/alist:beta`

### **Specify version**
See https://hub.docker.com/r/xhofe/alist for details
Pre-installed environment image suffix:

### **Image with built-in ffmpeg**
| Suffix | Desc |
|:---------|-------------------------------------------------------------------------|
| `aio` | An image that includes all of the following pre-installed environments. |
| `ffmpeg` | Pre-installed FFmpeg image for generating thumbnail for local storage |
| `aria2` | Pre-installed aria2 image for offline downloading. |

You can switch to image with out-of-the-box ffmpeg environment by adding `-ffmpeg` to any image tag.
You can append a suffix using the `-` symbol after any of the mirror tags to switch to an image with the corresponding environment. For example, `xhofe/alist:latest-aio` `xhofe/alist:beta-aria2` `xhofe/alist:v3.40.0-ffmpeg`

If the thumbnail feature is still not working, please verify the following:
If the thumbnail generation function still does not work when using the pre-installed ffmpeg, please confirm:

+ You are using local storage
+ Switched to grid view
+ The thumbnail switch in local storage driver settings is enabled
+ The configuration path for the thumbnail cache folder in local storage is correct, for example, `data/thumbnail`

::: tabs#Docker-ffmpeg
When using a pre-installed aria2 mirror, you might see errors like the following in the alist logs:

@tab latest
```
ERRO[2022-11-20 12:05:19] error [unaligned 64-bit atomic operation] while run task [download http://xxx.com/xxx.png to [/ftp](/)]
```

**docker-cli**
The solution is, if the CPU architecture is 64-bit, you can try to manually pull a 64-bit image or rebuild the container. If the CPU architecture is 32-bit, there is currently no available solution.

```bash
docker run -d --restart=unless-stopped -v /etc/alist:/opt/alist/data -p 5244:5244 -e PUID=0 -e PGID=0 -e UMASK=022 --name="alist" xhofe/alist:latest-ffmpeg
```
## See the admin's info:

**docker-compose**
#### Lower than v3.25.0

```bash
version: '3.3'
services:
alist:
image: 'xhofe/alist:latest-ffmpeg'
container_name: alist
volumes:
- '/etc/alist:/opt/alist/data'
ports:
- '5244:5244'
environment:
- PUID=0
- PGID=0
- UMASK=022
restart: unless-stopped
docker exec -it alist ./alist admin
```

@tab beta
#### Higher than v3.25.0

**docker-cli**
Versions above 3.25.0 change the password to an encrypted hash value, and the password cannot be calculated directly. If the password is forgotten, it can only be re-**`randomly generated`** or **`manually set`**

```bash
docker run -d --restart=unless-stopped -v /etc/alist:/opt/alist/data -p 5244:5244 -e PUID=0 -e PGID=0 -e UMASK=022 --name="alist" xhofe/alist:beta-ffmpeg
# Randomly generate a password
docker exec -it alist ./alist admin random
# Manually set a password, `NEW_PASSWORD` refers to the password you need to set
docker exec -it alist ./alist admin set NEW_PASSWORD
```

**docker-compose**

```bash
version: '3.3'
services:
alist:
image: 'xhofe/alist:beta-ffmpeg'
container_name: alist
volumes:
- '/etc/alist:/opt/alist/data'
ports:
- '5244:5244'
environment:
- PUID=0
- PGID=0
- UMASK=022
restart: unless-stopped
```
## **Update**
::: details docker-cli update
1. docker ps -a #View the container (find the ID of the Alist container)
2. docker stop ID #Stop Alist running, otherwise it cannot be deleted (this time the ID of the Alist container is d429749a6e69, it is different for each installation)
3. docker rm ID #Delete the Alist container (the data is still there as long as you don't delete it manually)
4. docker pull xhofe/alist:latest
5. [Enter the installation command and click to view](#docker-cli)
6. The update is complete, go and have a look.. It's that simple

**There is a missing step in the picture, it is step 4 in the tutorial....remember to execute**
![docker](/img/faq/updocker.png)
:::

### **User / Group Identifiers**
:::details docker-compose update
1. docker-compose pull

When using volumes (`-v` flags) permissions issues can arise between the host OS and the container, we avoid this issue by allowing you to specify the user `PUID` and group `PGID`.
2. docker-compose up -d

Ensure any volume directories on the host are owned by the same user you specify and any permissions issues will vanish like magic.
:::

In this instance `PUID=1000` and `PGID=1000`, to find yours use `id user` as below:
Q: My version is v3.x.x and I cannot upgrade to the latest version. `docker pull xhofe/alist:latest` does not work to pull the latest version. After changing to docker-compose, it is still version 3.x.x

```bash
$ id username
uid=1000(dockeruser) gid=1000(dockergroup) groups=1000(dockergroup)
```
A: The reason is that your docker has set up a mirror, and the latest version cannot be updated from the mirror, so modify /etc/docker/daemon.json and delete "registry-mirrors": ["mirror accelerator address"]

- If deletion doesn’t work, you can consider replacing it with a `mirror acceleration address`
- Or simple and rude: when downloading, replace `xhofe/alist:latest` with `xhofe/alist:v3.16.3` (specify the version, the latest when writing the tutorial is 3.16.3)

### **Manually build Docker image**
### **Compile Image**

Install Docker, clone the repository, and navigate to the root directory of the repository, no additional preparation is needed.
Install Docker, clone the repository, then navigate to the root directory of the repository. No further preparation is required.

::: tabs#Docker-build

Expand All @@ -203,52 +146,18 @@ Install Docker, clone the repository, and navigate to the root directory of the
docker build -t xhofe/alist:latest .
```

@tab with ffmpeg
@tab build-arg

```bash
docker build -t xhofe/alist:latest-ffmpeg --build-arg INSTALL_FFMPEG=true .
```

:::

## **Additional notes about the offline download feature**

If the image is not pulled using the '''docker pull --platform''' parameter, docker may pull the 32-bit image on the 64-bit operating system, which may cause the offline download function to be unavailable even under normal configuration.

When an error occurs, you will see a similar error log in Alist's log file.

```ERRO[2022-11-20 12:05:19] error [unaligned 64-bit atomic operation] while run task [download http://pic.rmb.bdstatic.com/bjh/34ee946f7a74435a167ca4351d723374.png to [/ftp](/)]```

Solution, if the CPU architecture is 64-bit, try to manually pull the 64-bit docker image, rebuild the container, and try again.

If the CPU architecture is 32-bit, there is currently no solution available.



## **How to update Docker installation?**

::: details docker-cli update
1. docker ps -a #View the container (find the ID of the Alist container)
2. docker stop ID #Stop Alist running, otherwise it cannot be deleted (this time the ID of the Alist container is d429749a6e69, it is different for each installation)
3. docker rm ID #Delete the Alist container (the data is still there as long as you don't delete it manually)
4. docker pull xhofe/alist:latest
5. [Enter the installation command and click to view](#docker-cli)
6. The update is complete, go and have a look.. It's that simple

**There is a missing step in the picture, it is step 4 in the tutorial....remember to execute**
![docker](/img/faq/updocker.png)
:::

:::details docker-compose update
1. docker-compose pull

2. docker-compose up -d

:::

Q: My version is v3.x.x and I cannot upgrade to the latest version. `docker pull xhofe/alist:latest` does not work to pull the latest version. After changing to docker-compose, it is still version 3.x.x

A: The reason is that your docker has set up a mirror, and the latest version cannot be updated from the mirror, so modify /etc/docker/daemon.json and delete "registry-mirrors": ["mirror accelerator address"]
Available build args:

- If deletion doesn’t work, you can consider replacing it with a `mirror acceleration address`
- Or simple and rude: when downloading, replace `xhofe/alist:latest` with `xhofe/alist:v3.16.3` (specify the version, the latest when writing the tutorial is 3.16.3)
| | Desc |
|:----------------------|----------------|
| `INSTALL_FFMPEG=true` | Install ffmpeg |
| `INSTALL_ARIA2=true` | Install aria2 |
Loading

0 comments on commit 00aa292

Please sign in to comment.