weewx-docker 🌩🐳

This docker container can be used to quickly get a WeeWX instance up and running.

Running

The easiest way to start the container is to create a docker-compose.yml similar to the following. If you use a serial port to connect to your weather station, make sure the container has permissions to access the port.

Modify any paths or devices as needed:

---
name: "weewx"

services:
  weewx:
    image: felddy/weewx:5
    volumes:
      - type: bind
        source: ./data
        target: /data
    devices:
      - "/dev/ttyUSB0:/dev/ttyUSB0"

1. Create a directory on the host to store the configuration and database files:

   mkdir data
   chown 1000:1000 data
   

2. If this is the first time running weewx, use the following command to start the container and generate a configuration file:

   docker compose run --rm weewx
   

3. The configuration file will be created in the data directory. You should edit this file to match the setup of your weather station.

4. When you are satisfied with configuration the container can be started in the background with:

   docker compose up --detach
   

Running as a different user

By default the container runs as the non-root weewx user (uid/gid 1000), which is why the data directory is assigned to 1000:1000 in the steps above.

The container also supports running under an arbitrary uid:gid.

services:
  weewx:
    image: felddy/weewx:5
    user: "1234:1234"
    volumes:
      - type: bind
        source: ./data
        target: /data

The only requirement is that the volume mounted at /data be writable by the uid the container runs as. For a bind mount, make the host directory writable by that user:

mkdir data
chown 1234:1234 data

Upgrading

1. Stop the running container:

   docker compose down
   

2. Pull the new images from the Docker hub:

   docker compose pull
   

3. Update your configuration file (a backup will be created):

   docker compose run --rm weewx station upgrade
   

4. Read through the new configuration and verify. It is helpful to diff the new config with the backup. Check the WeeWX Upgrade Guide for instructions for specific versions.

5. Start the container up with the new image version:

   docker compose up --detach
   

Migrating

If you are migrating a WeeWX installation, you need to configure the logger to write to the console. Add the following to your weewx.conf file to see the log output in the container logs:

[Logging]
    [[root]]
        level = INFO
        handlers = console,

Installing WeeWX Extensions

If arguments are passed to the container, they are forwarded on to the weectl command. This can be used to install extensions:

docker compose run --rm weewx \
  extension install --yes \
  https://github.com/matthewwall/weewx-windy/archive/master.zip

docker compose run --rm weewx \
  extension install --yes \
  https://github.com/matthewwall/weewx-mqtt/archive/master.zip

Installing Python Packages

To install and persist Python packages, use the pip command. The libraries will be installed into the data volume, ensuring they persist between container restarts.

docker compose run --rm --entrypoint pip weewx \
  install git+https://github.com/felddy/weewx-home-assistant@v1.0.0

Image tags

The images of this container are tagged with semantic versions that align with the version and build of WeeWX that they support.

[!TIP] It is recommended that users use the major version tag: :5 Using the major tag will ensure that you receive the most recent version of the software that is compatible with your saved data, and prevents inadvertent upgrades to a new major version.

See the tags tab on Docker Hub for a list of all the supported tags.

Volumes

Building from source

Build the image locally using this git repository as the build context:

docker build \
  --tag felddy/weewx:5.4.0 \
  https://github.com/felddy/weewx-docker.git#develop

Cross-platform builds

To create images that are compatible with other platforms you can use the buildx feature of Docker:

1. Copy the project to your machine using the Clone button above or the command line:

   git clone https://github.com/felddy/weewx-docker.git
   cd weewx-docker
   

2. Build the image using buildx:

   docker buildx build \
     --platform linux/amd64 \
     --output type=docker \
     --tag felddy/weewx:5.4.0 .
   

Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

License

This project is released as open source under the MIT license.

All contributions to this project will be released under the same MIT license. By submitting a pull request, you are agreeing to comply with this waiver of copyright interest.