How do you deploy a plugin?

[erawhctim]

Apologies if this is obvious, but for someone with zero context on Slack plugins or this repo, after reading through the docs it's not immediately clear how I would fork one of the example plugins and deploy it as a PoC/test. How does that work?

Would it make sense to add a section to the docs with some more explanation on this? Or is this covered somewhere else (e.g. Slack's own documentation)? Thanks in advance!

[DonDebonair]

Thanks for reaching out!

The Slack Machine docs definitely need some love in that regard. Just to be understand your question: are you clear on how to run/deploy Slack Machine itself and are you just trying to understand how to add your own plugins to it? Or do you also need help running/deploying Slack Machine itself?

And when you're talking about the example plugins, are you referring to sm-example-plugin?

[erawhctim]

I think I'm mostly lost on the latter option - running/deploying slack machine itself. The docs on installing/running the commands locally seem pretty clear and easy to follow to me 👍🏻 The main thing I'm unclear on is where the deployed plugin lives and how I would go about deploying it.

I think my comment re: the example plugin was confusing; maybe just disregard that 🙂

[DonDebonair]

Let me still try to explain both:

How do plugins get loaded?

Maybe we need to be clear on terminology: a plugin is anything that subclasses machine.plugins.base.MachineBasePlugin. Such a class can live in any Python module (e.g. my_module.py) and can be imported by Slack Machine.

So how does importing modules work?

In your Slack Machine configuration (i.e. local_settings.py) you have a PLUGINS setting that is a list of strings, where each string references a plugin class with the full Python module "path":

PLUGINS = [
    "machine.plugins.builtin.general.HelloPlugin",
    "machine.plugins.builtin.fun.memes.MemePlugin",
    "machine.plugins.builtin.fun.images.ImageSearchPlugin",
    "my_package.my_module.MyPlugin",
]

Now, Slack Machine will attempt to import these classes on startup, when you run the slack-machine command. For Slack Machine to find these classes, the modules they are in, need to be in the Python search path. What Slack Machine can find on that path is determined by a couple of things:

• The virtualenv you have activated
• The Python packages you have installed within that virtualenv
• Your current directory (from where you run slack-machine

Let's say you installed the following packages in your virtualenv:

pip install slack-machine
pip install https://github.com/DandyDev/sm-example-plugin # this is the example plugin I created

And you have the following directory structure:

my-project/
├─ my-package/
│  ├─ my_module.py
├─ local_settings.py

Now you can have the following valid PLUGINS setting in your local_settings.py:

PLUGINS = [
    "machine.plugins.builtin.general.HelloPlugin", # built-in plugin from slack-machine
	"example_plugin.my_plugin.MyPlugin", # available through the pip installed `sm-example-plugin` package
    "my_package.my_module.YourPlugin", # available through your local directory
]

Now when you run slack-machine it will load all these plugins.

TLDR: plugins can be picked up both from your local directory and through installed packages

How to deploy Slack Machine?

How you deploy Slack Machine is highly dependent on whether you want to run it on a virtual machine somewhere, inside a Docker container, on Heroku etc.

I personally deploy the bots I create with Slack Machine using Docker. My Dockerfiles look something like this:

ARG PYTHON_VERSION=3.10

FROM python:${PYTHON_VERSION}-slim-buster AS base

ENV \
    # do not buffer python output at all
    PYTHONUNBUFFERED=1 \
    # do not write `__pycache__` bytecode
    PYTHONDONTWRITEBYTECODE=1 \
    APP_DIR="/code"

FROM base as python-deps

ENV \
    # do not ask any interactive question
    POETRY_NO_INTERACTION=1 \
    # Poetry bin
    PATH="/root/.local/bin:${PATH}" \
    # Poetry version
    POETRY_VERSION=1.2.2

RUN apt-get -y update \
    && apt-get install -y --no-install-recommends curl \
    && apt-get -y auto-remove \
    && apt-get -y clean \
    && rm -rf /var/lib/apt/lists/* \
    && rm -rf /usr/share/doc/ \
    && rm -rf /usr/share/man/ \
    && rm -rf /usr/share/locale/

RUN curl -sSL https://install.python-poetry.org | python3 - && \
    poetry config virtualenvs.create true && \
    poetry config virtualenvs.in-project true

WORKDIR ${APP_DIR}/

COPY pyproject.toml poetry.lock ${APP_DIR}/

RUN poetry install --no-root

## Runtime image, only copies the venv
FROM base

COPY --from=python-deps ${APP_DIR}/.venv ${APP_DIR}/.venv/

ENV PATH=${APP_DIR}/.venv/bin:$PATH

COPY . ${APP_DIR}
WORKDIR ${APP_DIR}

CMD ["slack-machine"]

As you can see, I manage my dependencies (Python packages) through Poetry. You can also use pip if you want, the principle remains the same.

The last COPY command will copy any local code - my custom Slack Machine plugins - to the Docker image. This is on top of whatever Slack Machine plugins I have installed from Python packages, through Poetry

---

Let me know if this clarifies things a bit!

[erawhctim]

Amazing! This is exactly what I was looking for, and I really appreciate the detail you've added here (especially related to Poetry, as I'm not 100% keen on the latest and greatest in the Python world). Thank you!

[DonDebonair]

No problem, if you have any questions about Slack Machine in the future, don't hesitate to reach out here or in our (currently still super small) Slack community chat