Sopel for Docker
- Sopel Homepage @ Sopel, The Python IRC Bot
- Sopel GitHub @ sopel-irc/sopel
- Docker GitHub @ sopel-irc/docker-sopel
- Docker Registry @ sopelirc/sopel
Pull the docker image for the latest Sopel release (v6.6.3)
$ docker pull sopelirc/sopel:latest
Start your bot. Specify a name (e.g.,
my_first_sopel) for the container to make subsequent startups and shutdowns easier.
$ docker run --name=my_first_sopel -ti sopelirc/sopel
On the first run, you will be taken through the setup wizard to write the bot's configuration file. See the "First run" Sopel Wiki entry for more details.
Stopping and starting the bot
You can stop the bot started with the command above with a simple keyboard interrupt (
Ctrl-C), or use the docker stop command:
docker stop my_first_sopel
The bot can be restarted with the docker start command:
docker start -ia my_first_sopel.
Note: containers started with
docker start ...need to be stopped with
docker stop ...(
Ctrl-Cwill not work) as in the example above.
How to use this image
The minimum requirement for a Sopel bot is valid configuration file. You can create one by starting a new bot, or you can plug in a configuration file you already have! While Sopel already comes packaged with a wide variety of modules, you can easily add third-party and custom modules to your container.
Save a new configuration
Following the Quickstart steps will generate a configuration directory in the container's filesystem. You will likely want to extract this to your host for easier modification and persistence. You can use the copy command,
docker cp ..., to extract the
.cfg file or entire configuration folder to the directory of your choosing:
$ docker cp my_first_sopel:/home/sopel/.sopel/default.cfg /some/path/on/the/host/
copy the entire
~/.sopelconfiguration directory to
$ docker cp my_first_sopel:/home/sopel/.sopel /some/path/on/the/host/
The extracted configuration file/folder can now be transfered or copied to be used as a template for other bots.
Use an existing configuration
A configuration file or folder can be mounted at
/home/sopel/.sopel for use by the bot. The default configuration file name (
default.cfg) should be used, or the correct file name should be passed as an argument to the command by appending
-c correct_file_name.cfg to the
docker run ... command.
mount a configuration file
$ docker run -v "/path/to/my/default.cfg:/home/sopel/.sopel/default.cfg" ...
mount a configuration folder
$ docker run -v "/path/to/config/folder:/home/sopel/.sopel" ...
If you are having permission issues, use the
PGID environment variables to have the user in the container match the host ids. Alternately, you can change ownership of the configuration file/folder to match the container user (
Add third-party packages
Modules available from PyPI
You can also mount a pip
requirements.txt formatted file to
/pypi_packages.txt with a list of packages to be installed on startup.
Modules from source
Mount the module source directory into
/home/sopel/.sopel/modules, and Sopel will automatically recognize and load the module.
Alpine Linux packages
You can also mount a text file to
/apk_packages.txt with a list of packages to be installed on startup.
When you start the bot, you can adjust various settings related to the environment for the bot process by passing one or more environment variables on the
docker run ... command line.
sopel process runs with
100000 to prevent any unwanted/accidental access to host resources. This means that mounted volumes will need to allow read and write to a user with those ids. Instead, you can set these to change the ids of the sopel user on startup. For example,
$ docker run -e PUID=1000 ... Setting UID for user sopel to 1000... Done. ... ... Welcome to Sopel. Loading modules... ...
where, generally, you would set the
PGID to match the mounted volume owner ids.
Packages from PyPI can be installed at startup by providing a space separated list of package names. Since
pip install ... is being called under the hood, any pip-valid package name is acceptable. For example,
$ docker run -e EXTRA_PYPI_PACKAGES="sopel-modules.weather google-api-python-client sopel-modules.youtube" ... Installing package "sopel-modules.weather" with pip... ... Installing package "google-api-python-client" with pip... ... Installing package "sopel-modules.youtube" with pip... ... ... Welcome to Sopel. Loading modules... ...
Occasionally, you may need to install system packages to satisfy requirements for various Python packages. These packages can be specified as a space separated list of packages to be installed by
apk add --no-cache .... For example, you may need a database client, various tools required for compiling source code, and git to allow pip to install from a repository:
$ docker run -e EXTRA_APK_PACKAGES="mysql-client build-base git" ... Installing apk packages: mysql-client build-base git... ... ... Welcome to Sopel. Loading modules... ...
will install the required system packages.