Anki in Docker
==============

Anki can optionally be built and run with Docker, which will automate the
installation of Anki's build dependencies. The instructions below cover running
Docker on Linux; to run it on other platforms you will need to run an X server
and adapt the instructions.

For information on building Anki outside of Docker, please see README.development.

## Running Anki in Docker

Build and then run the image. The `docker run` command below runs the image as the
current user, and it mounts the user's `$HOME` directory, which is where Anki stores
its local files.

```
docker build --tag anki .
xhost +local:root  # Undo when done with `xhost -local:root`
docker run \
    --rm -it \
    --user 1000:1000 \
    --volume $HOME/.local/share:$HOME/.local/share:rw \
    --volume /etc/passwd:/etc/passwd:ro \
    --volume /tmp/.X11-unix:/tmp/.X11-unix:rw \
    --env DISPLAY=$DISPLAY \
    anki
xhost -local:root
```

## Developing Anki in Docker

Build your local source tree in Docker.

1. Build the Docker image with build-time dependencies. The Anki Dockerfile uses
multi-stage builds, so the target is the first stage, which includes only the
dependencies.

    ```
    docker build --tag anki:dependencies --target dependencies .
    ```

2. Compile your source tree

    Start the image with dependencies in the background. It is important to run the
    image as the current user, because otherwise, some files in the source tree will be
    owned by root. Find user id with `id -u` and group ID with `id -g`. These values
    are passed to `--user` as in `--user $(id -u):$(id -g)`.

    ```
    docker run --rm -it \
        --name ankibuilder \
        --detach \
        --workdir /work
        --volume "$PWD":/work:rw \
        --user 1000:1000 \
        --volume /etc/passwd:/etc/passwd:ro \
        --volume /tmp/.X11-unix:/tmp/.X11-unix:rw \
        --env DISPLAY=$DISPLAY \
        anki:dependencies bash
    ```

    Allow the Docker container to use the local X server and show the GUI.

    ```
    xhost +local:root
    ```

    (Undo this when done with `xhost -local:root`)

    Compile.

    ```
    docker exec -it ankibuilder make run
    ```

    The Anki graphical user interface should appear. The first run will take some time
    because Rust code has to be compiled and Python dependencies have to be downloaded,
    etc. The following runs will be much faster.

    To compile without running the GUI, use `make develop`.

3. Other common operations

    If system packages need to be installed, use `apt-get` as below. The Docker image
    is based on a Debian Stable image.

    ```
    docker exec -it --user root ankibuilder apt-get update
    docker exec -it --user root ankibuilder apt-get install PACKAGES
    ```

    An interactive bash shell can be started with

    ```
    docker exec -it ankibuilder bash
    ```

    or as root user

    ```
    docker exec -it --user root ankibuilder bash
    ```