anki/docs/docker.md

# Needs updating

The following was written before the build system changed, and will
need modifications to work.

# 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
    ```

Old docker file below:

```
ARG PYTHON_VERSION="3.8"

FROM python:$PYTHON_VERSION AS dependencies

# Allow non-root users to install things and modify installations in /opt.
RUN chmod 777 /opt && chmod a+s /opt

# Install rust.
ENV CARGO_HOME="/opt/cargo" \
    RUSTUP_HOME="/opt/rustup"
ENV PATH="$CARGO_HOME/bin:$PATH"
RUN mkdir $CARGO_HOME $RUSTUP_HOME \
    && chmod a+rws $CARGO_HOME $RUSTUP_HOME \
    && curl -fsSL --proto '=https' --tlsv1.2 https://sh.rustup.rs \
    | sh -s -- -y --quiet --no-modify-path \
    && rustup update \
    && cargo install ripgrep

# Install system dependencies.
RUN apt-get update \
    && apt-get install --yes --no-install-recommends \
    gettext \
    lame \
    libnss3 \
    libxcb-icccm4 \
    libxcb-image0 \
    libxcb-keysyms1 \
    libxcb-randr0 \
    libxcb-render-util0 \
    libxcb-xinerama0 \
    libxcb-xkb1 \
    libxkbcommon-x11-0 \
    libxcomposite1 \
    mpv \
    portaudio19-dev \
    rsync \
    && rm -rf /var/lib/apt/lists/*

# Install node and npm.
WORKDIR /opt/node
RUN curl -fsSL --proto '=https' https://nodejs.org/dist/v12.18.3/node-v12.18.3-linux-x64.tar.xz \
    | tar xJ --strip-components 1
ENV PATH="/opt/node/bin:$PATH"

# Install protoc.
WORKDIR /opt/protoc
RUN curl -fsSL --proto '=https' -O https://github.com/protocolbuffers/protobuf/releases/download/v3.11.4/protoc-3.11.4-linux-x86_64.zip \
    && unzip protoc-3.11.4-linux-x86_64.zip -x readme.txt \
    && rm protoc-3.11.4-linux-x86_64.zip
ENV PATH="/opt/protoc/bin:$PATH"

# Allow non-root users to install toolchains and update rust crates.
RUN chmod 777 $RUSTUP_HOME/toolchains $RUSTUP_HOME/update-hashes $CARGO_HOME/registry \
    && chmod -R a+rw $CARGO_HOME/registry \
    # Necessary for TypeScript.
    && chmod a+w /home

# Build anki. Use a separate image so users can build an image with build-time
# dependencies.
FROM dependencies AS builder
WORKDIR /opt/anki
COPY . .
RUN make develop

FROM builder AS pythonbuilder
RUN make build

# Build final image.
FROM python:${PYTHON_VERSION}-slim

# Install system dependencies.
RUN apt-get update \
    && apt-get install --yes --no-install-recommends \
    gettext \
    lame \
    libnss3 \
    libxcb-icccm4 \
    libxcb-image0 \
    libxcb-keysyms1 \
    libxcb-randr0 \
    libxcb-render-util0 \
    libxcb-xinerama0 \
    libxcb-xkb1 \
    libxkbcommon-x11-0 \
    libxcomposite1 \
    mpv \
    portaudio19-dev \
    rsync \
    && rm -rf /var/lib/apt/lists/*

# Install pre-compiled Anki.
COPY --from=pythonbuilder /opt/anki/dist/ /opt/anki/
RUN python -m pip install --no-cache-dir \
    PyQtWebEngine \
    /opt/anki/*.whl \
    # Create an anki executable.
    && printf "#!/usr/bin/env python\nimport aqt\naqt.run()\n" > /usr/local/bin/anki \
    && chmod +x /usr/local/bin/anki \
    # Create non-root user.
    && useradd --create-home anki

USER anki

ENTRYPOINT ["/usr/local/bin/anki"]

LABEL maintainer="Jakub Kaczmarzyk <jakub.kaczmarzyk@gmail.com>"
```