Add Dockerfile, docs, and ci check.

Author: jzohrab

.dockerignore

@@ -0,0 +1,14 @@
+# Only include the lute/ folder.
+#
+# On mac, to find all directories and sizes:
+#   du -hd 1
+#
+.git/
+.pytest_cache/
+.venv/
+__pycache__/
+dist/
+htmlcov/
+tests/
+utils/
+data/

.github/workflows/ci.yml

@@ -100,12 +100,35 @@ jobs:
         # Verify with utils script back in the workspace
         # (verify.py is not included in flit install)
         pushd ${{ github.workspace }}
-        python -m utils.verify
+        python -m utils.verify 5000
         popd
 
         pkill -f "python -m lute.main"   # Kill that process.
 
 
+  # Test build docker container and try running.
+  # Slightly wasteful re-setup of node.
+  docker-build:
+    runs-on: ubuntu-latest
+    needs: base-ci
+    steps:
+    - uses: actions/checkout@v3
+    - uses: actions/setup-python@v4
+      with:
+        python-version: 3.11
+        cache: 'pip' # caching pip dependencies
+    - run: pip install -r requirements.txt
+    - name: Test docker build
+      run: |
+        docker build -f docker/Dockerfile --build-arg INSTALL_MECAB=false -t lute3 .
+        # Run container in the background, and check.
+        docker run -d -p 5000:5000 -v ./my_data:/lute_data -v ./my_backups:/lute_backup --name my-lute lute3:latest
+        sleep 10  # Give it a moment to start.
+        python -m utils.verify 5000
+        docker stop my-lute
+        docker rm my-lute
+
+
   # Generate a coverage badge, don't worry if it fails.
   # Uses https://github.com/Schneegans/dynamic-badges-action to update a secret gist
   # (ID a15001ec2ff889f7be0b553df9881566) and an API token, per notes at
@@ -235,4 +258,4 @@ jobs:
     - name: Verify flit install
       run: |
         cd ${{ github.workspace }}
-        python -m utils.verify
+        python -m utils.verify 5000

.gitignore

@@ -6,6 +6,9 @@ lute/config/config.yml
 *.ini
 *.ini.bkp
 
+docker/docker-compose.yml
+docker-compose.yml
+
 # user data
 data/
 

docker/Dockerfile

@@ -0,0 +1,27 @@
+# Official python base image.
+FROM python:3.11-slim-bookworm
+
+# Define a build argument with a default value.
+ARG INSTALL_MECAB=false
+
+# Install mecab for Japanese support if INSTALL_MECAB is true, e.g.
+#   docker build --build-arg INSTALL_MECAB=true -t lute3 .
+RUN if [ "$INSTALL_MECAB" = "true" ]; then \
+    apt-get update -y && \
+    apt-get install -y mecab mecab-ipadic-utf8 && \
+    apt-get clean && rm -rf /var/lib/apt/lists/*; \
+    fi
+
+# Lute code and config.
+COPY requirements.txt .
+ENV PIP_ROOT_USER_ACTION=ignore
+RUN pip install -r requirements.txt
+COPY lute /lute
+RUN mv /lute/config/config.yml.docker /lute/config/config.yml
+
+EXPOSE 5000
+
+# Start script.
+COPY docker/check_mounts_and_start.sh /lute/start.sh
+RUN chmod +x /lute/start.sh
+ENTRYPOINT ["/lute/start.sh"]

docker/README.md

@@ -0,0 +1,80 @@
+# The docker container
+
+The Dockerfile can be used to create two variants: one with mecab and dictionary (800+ MB) , and one without (300 MB).
+
+## Building
+
+Sample build, run from the root folder.  `INSTALL_MECAB` is `true` or `false`
+
+```
+docker build -f docker/Dockerfile --build-arg INSTALL_MECAB=false -t lute3 .
+```
+
+## Starting
+
+The Docker image is configured to write to directories in the container which must be mounted from the host:
+
+* `/lute_data`: the database, user images, etc.
+* `/lute_backup`: your backups
+
+If these directories are not mounted, the container will not start.
+
+### From the command line:
+
+```
+docker run -p 5000:5000 -v ./my_data:/lute_data -v ./my_backups:/lute_backup --name my-lute lute3:latest
+```
+
+The above:
+
+* runs the container from the lute3:latest image
+* exposes port 5000 on the host (so localhost:5000 works)
+* mounts the necessary directories
+* names the container "my-lute".
+
+### From a compose file
+
+```
+# Sample docker-compose.yml file
+version: '3.9'
+services:
+  lute:
+    image: lute3:latest
+    name: my-lute
+    ports:
+      - 5000:5000
+    volumes:
+      - ./my_data:/lute_data
+      - ./my_backups:/lute_backup
+```
+
+With that file in some location, you could do:
+
+```
+docker compose up -d
+```
+
+A `docker-compose.yml.example' is provided as a starting point in this directory -- copy that to a docker-compose.yml file in project root and use it:
+
+```
+docker compose up -d
+
+python -m utils.verify
+
+docker compose stop lute
+```
+
+## Stopping
+
+If you started the container from the command line, you'll need to get the container ID, and then stop it.
+
+```
+docker ps   # lists all running IDs
+docker stop <containerID>   # ID found in prev. command
+```
+
+If you started it with `docker compose`, you can do
+
+```
+docker compose stop
+```

docker/check_mounts_and_start.sh

@@ -0,0 +1,30 @@
+#!/bin/sh
+#
+# Check that the folders given in the
+# lute/config/config.yml.docker are in fact mounted.
+
+for d in /lute_data /lute_backup; do
+    checkdir=`mount | grep "$d"`
+    if [ -z "$checkdir" ]
+    then
+        echo ""
+        echo "-------------------------------------------------------"
+        echo "$d container directory is not mounted, quitting."
+        echo ""
+        echo "Lute (containerized) writes to /lute_data and lute_backup."
+        echo "BOTH of these must be mounted."
+        echo ""
+        echo "If these folders are not mounted from host directories,"
+        echo "then the writes will go to the container's writable layer,"
+        echo "and would be destroyed if the container were deleted."
+        echo "That would mean loss of data, so this check prevents it."
+        echo ""
+        echo "Please ensure you mount a host directory,"
+        echo "either in your docker-compose.yml or in your docker run."
+        echo "-------------------------------------------------------"
+        echo ""
+        exit
+    fi
+done
+
+python -m lute.main

docker/docker-compose.yml.example

@@ -0,0 +1,13 @@
+# Sample docker-compose.yml file.
+#
+version: '3.9'
+services:
+  lute:
+    image: lute3:latest
+    ports:
+      - 5000:5000
+    volumes:
+      # Note: you should change these directories
+      # to absolute paths (e.g. "/usr/yourname/etc/my_data")
+      - ./my_data:/lute_data
+      - ./my_backups:/lute_backup

docs/development.md

@@ -99,6 +99,10 @@ Todos are in the code as comments, e.g. `# TODO [<group name>:] detail`, `<!-- T
 `inv todos` collects all of these in a simple report.
 
 
+# Docker
+
+Notes for building and running a Docker container are at ../docker/README.com.
+
 # Misc dev notes
 
 ## read-only db during tests

lute/config/config.yml.docker

@@ -10,8 +10,18 @@ DATAPATH: /lute_data
 BACKUP_PATH: /lute_backup
 
 # Value to set in environment MECAB_PATH.
-# _May_ be needed for docker, if natto-py
-# can't find it automatically in the base image.
-# MECAB_PATH: xyz
+# The current build of the container can't find mecab,
+# so we have to set it here.
+#
+# To find the correct path, first build and run the container,
+# then connect to it, and find libmecab.so.2 like this:
+#
+# $ docker exec -it lute_v3-lute-1 bash
+# root@cid/# which mecab
+# /usr/bin/mecab
+# root@cid:/# ldd /usr/bin/mecab
+#    ...
+#    libmecab.so.2 => /lib/aarch64-linux-gnu/libmecab.so.2 (0x0000ffff9b540000)
+MECAB_PATH: /lib/aarch64-linux-gnu/libmecab.so.2
 
 IS_DOCKER: true

lute/main.py

@@ -58,11 +58,20 @@ def start():
     Running at:
 
     http://localhost:{port}
+    """
+    )
 
+    close_msg = """
     When you're finished reading, stop this process
     with Ctrl-C or your system equivalent.
     """
-    )
+    if app_config.is_docker:
+        close_msg = """
+        When you're finished reading, stop this container
+        with Ctrl-C, docker compose stop, or docker stop <containerid>
+        as appropriate.
+        """
+    _print(close_msg)
 
     serve(app, host="0.0.0.0", port=port)
 

utils/verify.py

@@ -5,21 +5,19 @@
 
 Usage:
 
-python -m utils.verify
+python -m utils.verify [port]
 """
 
+import sys
 import json
 import requests
-from lute.config.app_config import AppConfig
 
 
-def verify():
+def verify(port):
     """
     Check the /info page.
     """
 
-    app_config = AppConfig.create_from_config()
-    port = app_config.port
     url = f"http://localhost:{port}/info"
     resp = requests.get(url, timeout=5)
     c = resp.status_code
@@ -32,4 +30,10 @@ def verify():
 
 
 if __name__ == "__main__":
-    verify()
+    useport = None
+    if len(sys.argv) == 2:
+        useport = sys.argv[1]
+    else:
+        print("Must supply port as argument")
+        sys.exit(1)
+    verify(useport)