Scripts utilized with our Alpine Base docker image

📄 Alpine Base - Core Scripts 📄

This branch docker/core contains a set of scripts which are utilized when building the Keeweb Alpine Base Image.

• About
• Before Building
  • LF over CRLF
  • Set +x / 0755 Permissions
• Build docker/alpine-base Image
  • amd64
  • arm64 / aarch64
• Build docker/keeweb Image
  • amd64
  • arm64 / aarch64
  • hub.docker.com / ghcr.io / local
  • Image Tags
• Using docker/keeweb Image
  • docker run
  • docker-compose.yml
• Extra Notes
  • Custom Scripts
  • SSL Certificates
  • Access Shell / Bash
  • Logs

The scripts contained within this branch docker/core are called upon from the Keeweb Alpine Base image. The Alpine base image does NOT contain Keeweb, it only contains the alpine operating system, a minimal amount of packages, and Nginx. It is used as the foundation for which the docker/keeweb docker image will be built.

To build a docker image for Keeweb, you need two different docker images:

• Step 1: Build docker/alpine-base image
  • When being build, the alpine-base Dockerfile will grab and install the files from this branch docker/core
• Step 2: Build docker/keeweb image
• Step 3: Release the docker image built from Step 2 to Github's Ghcr.io or hub.docker.com

This branch contains no Dockerfile files. It only contains files that will be called upon by the docker/alpine-base image when it is built by the following files:

• docker/alpine-base/Dockerfile
• docker/alpine-base/Dockerfile.aarch64

When you build the docker/alpine-base image, the files in this branch docker/core will be fetched by docker/alpine-base Dockerfile and packaged with the alpine-base image via the following code:

ADD --chmod=755 "https://raw.githubusercontent.com/keeweb/keeweb/docker/core/docker-images.${MODS_VERSION}" "/docker-images"
ADD --chmod=755 "https://raw.githubusercontent.com/keeweb/keeweb/docker/core/package-install.${PKG_INST_VERSION}" "/etc/s6-overlay/s6-rc.d/init-mods-package-install/run"
ADD --chmod=755 "https://raw.githubusercontent.com/keeweb/keeweb/docker/core/kwown.${KWOWN_VERSION}" "/usr/bin/kwown"

kwown is vital and must be included in the base image you build. It is what controls the USER : GROUP permissions that will be handled within your docker image.

For this reason, there are a few requirements you can read about below in the section Before Building.

Prior to building the docker/alpine-base and docker/keeweb docker images, you must ensure the following conditions are met. If the below tasks are not performed, your docker container will throw the following errors when started:

• Failed to open apk database: Permission denied
• s6-rc: warning: unable to start service init-adduser: command exited 127
• unable to exec /etc/s6-overlay/s6-rc.d/init-envfile/run: Permission denied
• /etc/s6-overlay/s6-rc.d/init-adduser/run: line 34: kwown: command not found
• /etc/s6-overlay/s6-rc.d/init-adduser/run: /usr/bin/kwown: cannot execute: required file not found

You cannot utilize Windows' Carriage Return Line Feed. All files must be converted to Unix' Line Feed. This can be done with Visual Studio Code. OR; you can run the Linux terminal command dos2unix to convert these files.

For the branches docker/alpine-base and docker/keeweb, you can use the following recursive commands:

# Change ALL files
find ./ -type f | grep -Ev '.git|*.jpg|*.jpeg|*.png' | xargs dos2unix --

# Change run / binaries
find ./ -type f -name 'run' | xargs dos2unix --

For the branch docker/core, you can use the following commands:

dos2unix docker-images.v3
dos2unix kwown.v1
dos2unix package-install.v1
dos2unix with-contenv.v1

The files contained within this repo MUST have chmod 755 / +x executable permissions. If you are using the Keeweb Github Workflow, this is done automatically. If you are builting the images manually; you need to do this. Ensure those files have the correct permissions prior to building the Alpine base docker image.

If you are building the docker/alpine-base or docker/keeweb images, you must ensure the files in those branches have the proper permissions. All of the executable files are named run:

find ./ -name 'run' -exec chmod +x {} \;

If you want to set the permissions manually, run the following:

sudo chmod +x /root/etc/s6-overlay/s6-rc.d/init-adduser/run
sudo chmod +x /root/etc/s6-overlay/s6-rc.d/init-crontab-config/run
sudo chmod +x /root/etc/s6-overlay/s6-rc.d/init-custom-files/run
sudo chmod +x /root/etc/s6-overlay/s6-rc.d/init-envfile/run
sudo chmod +x /root/etc/s6-overlay/s6-rc.d/init-folders/run
sudo chmod +x /root/etc/s6-overlay/s6-rc.d/init-keygen/run
sudo chmod +x /root/etc/s6-overlay/s6-rc.d/init-migrations/run
sudo chmod +x /root/etc/s6-overlay/s6-rc.d/init-nginx/run
sudo chmod +x /root/etc/s6-overlay/s6-rc.d/init-permissions/run
sudo chmod +x /root/etc/s6-overlay/s6-rc.d/init-php/run
sudo chmod +x /root/etc/s6-overlay/s6-rc.d/init-samples/run
sudo chmod +x /root/etc/s6-overlay/s6-rc.d/init-version-checks/run
sudo chmod +x /root/etc/s6-overlay/s6-rc.d/svc-cron/run
sudo chmod +x /root/etc/s6-overlay/s6-rc.d/svc-nginx/run
sudo chmod +x /root/etc/s6-overlay/s6-rc.d/svc-php-fpm/run

For the branch docker/core, there are a few files to change. The ending version number may change, but the commands to change the permissions are as follows:

sudo chmod +x docker-images.v3
sudo chmod +x kwown.v1
sudo chmod +x package-install.v1
sudo chmod +x with-contenv.v1

The scripts contained within this docker/core branch do not need anything done to them. In order to use these scripts, clone the Keeweb Alpine Base branch docker/alpine-base:

git clone -b docker/alpine-base https://github.com/keeweb/keeweb.git .

Once cloned, the calls to include the scripts in this docker/core branch are within the Dockerfile and Dockerfile.aarch64. All you need to do is simply build your alpine-base image:

# Build keeweb alpine-base amd64
docker build --build-arg VERSION=3.20 --build-arg BUILD_DATE=20241216 -t alpine-base:latest -t alpine-base:3.20-amd64 -f Dockerfile .

# Build keeweb alpine-base arm64
docker build --build-arg VERSION=3.20 --build-arg BUILD_DATE=20241216 -t alpine-base:3.20-arm64 -f Dockerfile.aarch64 .

The flow of the process is outlined below:

%%{init: { 'themeVariables': { 'fontSize': '10px' }}}%%
flowchart TB

subgraph GRAPH_KEEWEB ["Build keeweb:latest"]
    direction TB
    obj_step10["`> git clone -b docker/keeweb github.com/keeweb/keeweb.git`"]
    obj_step11["`**Dockerfile
     Dockerfile.aarch64**`"]
    obj_step12["`> docker build \
    --build-arg VERSION=1.19.0 \
    --build-arg BUILD_DATE=20241216 \
    -t keeweb:latest \
    -t keeweb:1.19.0-amd64 \
    -f Dockerfile . \`"]
    obj_step13["`Download **alpine-base** from branch **docker/alpine-base**`"]
    obj_step14["`New Image: **keeweb:latest**`"]

    style obj_step10 text-align:center,stroke-width:1px,stroke:#555
    style obj_step11 text-align:left,stroke-width:1px,stroke:#555
    style obj_step12 text-align:left,stroke-width:1px,stroke:#555
    style obj_step13 text-align:left,stroke-width:1px,stroke:#555
end

style GRAPH_KEEWEB text-align:center,stroke-width:1px,stroke:transparent,fill:transparent

subgraph GRAPH_ALPINE["Build alpine-base:latest Image"]
direction TB
    obj_step20["`> git clone -b docker/alpine-base github.com/keeweb/keeweb.git`"]
    obj_step21["`**Dockerfile
     Dockerfile.aarch64**`"]
    obj_step22["`> docker build \
    --build-arg VERSION=3.20 \
    --build-arg BUILD_DATE=20241216 \
    -t docker-alpine-base:latest \
    -t docker-alpine-base:3.20-amd64 \
    -f Dockerfile . \`"]
    obj_step23["`Download files from branch **docker/core**`"]
    obj_step24["`New Image: **alpine-base:latest**`"]

    style obj_step20 text-align:center,stroke-width:1px,stroke:#555
    style obj_step21 text-align:left,stroke-width:1px,stroke:#555
    style obj_step22 text-align:left,stroke-width:1px,stroke:#555
    style obj_step23 text-align:left,stroke-width:1px,stroke:#555
end

style GRAPH_ALPINE text-align:center,stroke-width:1px,stroke:transparent,fill:transparent

GRAPH_KEEWEB --> obj_step10 --> obj_step11 --> obj_step12 --> obj_step13 --> obj_step14
GRAPH_ALPINE --> obj_step20 --> obj_step21 --> obj_step22 --> obj_step23 --> obj_step24

Once the base alpine image is built, you can now build the actual docker version of Keeweb. The files for this docker image are stored in the branch docker/keeweb:

• https://github.com/keeweb/keeweb/tree/docker/keeweb

After the docker/alpine-base image is built, you can now use that docker image as a base to build the docker/keeweb image. Navigate to the branch docker/keeweb and open the files:

• Dockerfile
• Dockerfile.aarch64

Next, specify the docker/alpine-base image which will be used as the foundation of the docker/keeweb image:

FROM ghcr.io/keeweb/alpine-base:3.20-amd64

After you have completed configuring the docker/keeweb Dockerfile, you can now build the official version of Keeweb. Remember to build an image for both amd64 and aarch64.

For the argument VERSION; specify the current release of Keeweb which will be contained within the docker image. It should be in the format of YYYYMMDD:

# Build docker/keeweb amd64
docker build --build-arg VERSION=1.19.0 --build-arg BUILD_DATE=20241216 -t keeweb:latest -t keeweb:1.19.0 -t keeweb:1.19.0-amd64 -f Dockerfile .

# Build docker/keeweb arm64
docker build --build-arg VERSION=1.19.0 --build-arg BUILD_DATE=20241216 -t keeweb:1.19.0-arm64 -f Dockerfile.aarch64 .

After you have your docker/keeweb image built, you can either upload the image to a public repository such as:

• hub.docker.com (Docker Hub)
• ghcr.io (Github)

After it is uploaded, you can use the docker run command, or create a docker-compose.yml, and call the docker image to be used.

This is discussed in the section Using docker/keeweb Image below.

When building your images with the commands provided above, ensure you create two sets of tags:

the amd64 arch gets a few extra tags because it should be the default image people clone.

To use the new docker/keeweb image, you can either call it with the docker run command, or create a new docker-compose.yml and specify the image:

If you want to use the keeweb docker image in the docker run command, execute the following:

docker run -d --restart=unless-stopped -p 443:443 --name keeweb -v ${PWD}/keeweb:/config ghcr.io/keeweb/keeweb:latest

If you'd much rather use a docker-compose.yml file and call the keeweb image that way, create a new folder somewhere:

mkdir -p /home/docker/keeweb

Then create a new docker-compose.yml file and add the following:

sudo nano /home/docker/keeweb/docker-compose.yml

services:
    keeweb:
        container_name: keeweb
        image: ghcr.io/keeweb/keeweb:latest          # Github image
      # image: keeweb/keeweb:latest                  # Dockerhub image
        restart: unless-stopped
        volumes:
            - ./keeweb:/config
        environment:
            - PUID=1000
            - PGID=1000
            - TZ=Etc/UTC

Once the docker-compose.yml is set up, you can now start your keeweb container:

cd /home/docker/keeweb/
docker compose up -d

Keeweb should now be running as a container. You can access it by opening your browser and going to:

http://container-ip
https://container-ip

The following are other things to take into consideration when creating the docker/alpine-base and docker/keeweb images:

The docker/alpine-base and docker/keeweb images support the ability of adding custom scripts that will be ran when the container is started. To create / add a new custom script to the container, you need to create a new folder in the container source files /root folder

mkdir -p /root/custom-cont-init.d/

Within this new folder, add your custom script:

nano /root/custom-cont-init.d/my_customs_script

#!/bin/bash

echo "**** INSTALLING BASH ****"
apk add --no-cache bash

When you create the docker image, this new script will automatically be loaded. You can also do this via the docker-compose.yml file by mounting a new volume:

services:
    keeweb:
        volumes:
            - ./keeweb:/config
            - ./custom-scripts:/custom-cont-init.d:ro

The docker/keeweb image already contains a custom script called /root/custom-cont-init.d/plugins. Do NOT edit this script. It is what automatically downloads the official Keeweb plugins and adds them to the container.

This docker image automatically generates an SSL certificate when the nginx server is brought online.

You may opt to either use the generated self-signed certificate, or you can add your own. If you decide to use your own self-signed certificate, ensure you have mounted the /config volume in your docker-compose.yml:

services:
    keeweb:
        container_name: keeweb
        image: ghcr.io/keeweb/keeweb:latest          # Github image
      # image: keeweb/keeweb:latest                  # Dockerhub image
        restart: unless-stopped
        volumes:
            - ./keeweb:/config

Then navigate to the newly mounted folder and add your 📄 cert.crt and 🔑 cert.key files to the 📁 /keeweb/keys/* folder.

You can access the docker container's shell by running:

docker exec -it keeweb ash

This image spits out detailed information about its current progress. You can either use docker logs or a 3rd party app such as Portainer to view the logs.

 Migrations   : Started
 Migrations   : 01-nginx-site-confs-default › Skipped
 Migrations   : Complete
──────────────────────────────────────────────────────────────────────────────────────────
                              Keeweb Password Manager                             
──────────────────────────────────────────────────────────────────────────────────────────
  Thanks for choosing Keeweb. Get started with some of the links below:

        Official Repo           https://github.com/keeweb/keeweb
        Official Site           https://keeweb.info/
        Beta Demo               https://beta.keeweb.info/
        Web App                 https://app.keeweb.info/
        Favicon Service         https://services.keeweb.info/favicon

  If you are making this copy of Keeweb available on a public-facing domain,
  please consider using Traefik and Authentik to protect this container from
  outside access.

        User:Group              1000:1000
        (Ports) HTTP/HTTPS      80/443
──────────────────────────────────────────────────────────────────────────────────────────

 SSL          : Using existing keys found in /config/keys
 Loader       : Custom files found, loading them ...
 Loader       : Executing ...
 Loader       : Checking keeweb-plugins
 Loader       : keeweb-plugins already installed in /config/www/plugins; skipping
 Loader       : plugins: Exited 0
 Core         : Completed loading container