diff --git a/.github/workflows/container.yml b/.github/workflows/container.yml new file mode 100644 index 0000000..12a9aaf --- /dev/null +++ b/.github/workflows/container.yml @@ -0,0 +1,43 @@ +name: Docker Builds + +on: [workflow_dispatch] + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v2 + + - name: Set up QEMU + uses: docker/setup-qemu-action@v1 + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v1 + + - name: Cache Docker layers + uses: actions/cache@v2 + with: + path: /tmp/.buildx-cache + key: ${{ runner.os }}-buildx-${{ github.sha }} + restore-keys: | + ${{ runner.os }}-buildx- + + - name: Log in to GHCR + if: github.event_name != 'pull_request' + uses: docker/login-action@v1 + with: + registry: ghcr.io + username: ${{ github.repository_owner }} + password: ${{ secrets.GITHUB_TOKEN }} + + - name: Build and push to ghcr + uses: docker/build-push-action@v2 + with: + context: . + file: ./Dockerfile + platforms: linux/amd64,linux/386,linux/arm64,linux/arm/v6,linux/arm/v7 + push: ${{ github.event_name != 'pull_request' }} + tags: | + ghcr.io/bklofas/kplex:latest + diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..a705ca5 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,21 @@ +FROM debian:stretch-slim +LABEL "name"="kplex" \ + "description"="A multiplexer for various nmea 0183 interfaces" + +ENV APP=/usr/src/app + +WORKDIR $APP + +COPY . $APP + +RUN apt-get update && apt-get install -y \ + make \ + build-essential \ + pkg-config \ + && make \ + && apt-get remove -y make build-essential pkg-config \ + && apt-get autoremove -y \ + && rm -rf /var/lib/apt/lists/* + +CMD $APP/kplex + diff --git a/README b/README index 2791e88..49da34b 100644 --- a/README +++ b/README @@ -56,10 +56,82 @@ the serial ports (normally "dialout" on modern debian-based systems). The configuration file the .deb installation installs in /etc/kplex.conf actually does nothing (all directives are commented out). Read the instructions -in this README file for how to create a confiuration file. A quick start +in this README file for how to create a configuration file. A quick start example which bridges between a tcp server and a 38400 baud serial-to-usb connection is commented out in this example file. +Docker +------ +kplex can now run in a Docker container. There are no dependencies to install, +and nothing to build. The final image size is about 55 to 75 MB depending on +the host architecture. + +Two options for obtaining the container: Either download and run a pre-built +container, or build the container locally. + +Just to test things out on a pre-built container: +docker run -it --rm --network=host -v /home/user/kplex.conf:/etc/kplex.conf:ro ghcr.io/bklofas/kplex:latest + +* This downloads a pre-built container from the Github container registry. +* Architectures supported are i386, amd64, arm32v6, arm32v7, and arm64. Tested + on amd64, arm32v7, and arm64. arm packages run on all RaspberryPi flavors. Your + client will automatically download the appropriate architecture. +* --network=host: Allows the container to talk to the internet, if you are + sending the packets to an online service. +* -v /home/user/kplex.conf:/etc/kplex.conf:ro This mounts kplex.conf (from your + home directory) into the container's /etc folder (read-only), when the container is started. + kplex looks in /etc for configuration files during startup. +* To add command-line options, add ./kplex [OPTIONS] on the end. +* Ctrl-C to kill the container. +* Using the --rm flag will delete the container when you kill it. Otherwise, + it will stay around until you prune. + +For a more permanent setup, run the container in the background: +docker run -d --name kplex --restart=unless-stopped --log-driver=local --network=host -v ~/kplex.conf:/etc/kplex.conf:ro ghcr.io/bklofas/kplex:latest ./kplex -d 4 + +* -d: Start this container in daemon/background mode. +* --name: Name this anything you want. +* --restart=unless-stopped: Automatically restart the container if something + happens (reboot, USB problem), unless you have manually stopped the container. +* --log-driver=local: By default, docker uses the json log driver which may fill + up your harddrive, depending on how busy your station is. local log driver + defaults to 100MB of saved logs, and automatically rotates them. +* ./kplex -d 4: Debug command line options. Optional if all the configuration + is in the kplex.conf file. +* After you make any edits to kplex.conf, reload the container with "docker + restart kplex". +* If you want to bring real serial devices into the container, add + "--device=/dev/ttyS0" to the command line +* For USB-serial devices, you could use "--device=/dev/ttyUSB0" or similar, but + it's probably better to specify the USB devices by ID. Look in /dev/serial/by-id, + and add "--device=/dev/serial/by-id/usb-Prolific_Tech..." or similar. This will + ensure the same device is used across reboots. Use the same path in the kplex.conf + file. For example: + [serial] + filename=/dev/ttyS0 or /dev/ttyUSB0 or /dev/serial/by-id/usb-Prolific_Tech.... + direction=in + baud=4800 +* View the startup messages (if any) and output with "docker logs --follow kplex". +* Stop the container with "docker stop kplex". + +Building the container: + +Clone the repository with "git clone https://github.com/stripydog/kplex.git", then +from that folder "docker build -t kplex:1.0 ." + +Or, build the container without cloning the repository: +"docker build https://github.com/stripydog/kplex.git" + +Other tips and tricks: + +* If you have this [file] STDOUT directive in your kplex.conf file, you can see + the individual AIS packets with "docker logs --follow kplex". + [file] + filename=- + direction=out + + + Invocation: -----------