pretix-plugins/README.md

# Pretix Plugins

A community-maintained mono-repository of custom pretix plugins and tooling to
build a bundled Docker image for use with the
[Co-op Cloud pretix recipe](https://git.coopcloud.tech/coop-cloud/pretix).

---

## How it works

```
plugins/                   ← plugin source code lives here (Python packages)
  my-plugin/
    pretix_my_plugin/
    setup.py
plugins.txt                ← select which plugins go into the Docker image
Dockerfile                 ← builds the image from plugins.txt
.gitea/workflows/          ← CI: automatically builds & pushes image on every tag
```

Each plugin is a standard Python package inside `plugins/`. The `plugins.txt`
file controls which of those plugins (and optionally any PyPI or external
plugins) are installed into the final Docker image.

The resulting image is a drop-in replacement for `pretix/standalone` and is
used via the optional `compose.plugin.yml` override in the pretix recipe.

---

## Using the image in your pretix deployment

In your app `.env` file (managed by abra):

```bash
COMPOSE_FILE=compose.yml:compose.plugin.yml
PRETIX_PLUGIN_IMAGE=git.coopcloud.tech/coop-cloud/pretix-plugins:1.0.0
```

If `PRETIX_PLUGIN_IMAGE` is not set, the standard `pretix/standalone` image
is used — operators who do not need plugins are not affected at all.

---

## Selecting plugins

Edit `plugins.txt` to choose which plugins are included in your image.
Each non-empty, non-comment line is passed directly to `pip install`.

```
# Local plugins from this repo (recommended for custom plugins):
./plugins/attendance_confirm_plugin/
./plugins/selective_export_plugin/

# Community plugins from PyPI:
pretix-pages

# External plugins via Git URL:
git+https://git.coopcloud.tech/other-org/pretix-some-plugin.git@1.0.0
```

Comment out or remove a line to exclude a plugin from the image.

---

## Building and publishing the image


### Manual

```bash
docker build -t git.coopcloud.tech/coop-cloud/pretix-plugins:1.0.0 .
docker push git.coopcloud.tech/coop-cloud/pretix-plugins:1.0.0
```

---

## Contributing a plugin

1. Create a new directory under `plugins/` named after your plugin:
   ```
   plugins/my-new-plugin/
   ```

2. Add a valid pretix plugin Python package inside it (see structure below).

3. Add it to `plugins.txt` if you want it included in the default image build.

4. Open a pull request.

### Required plugin structure

```
plugins/my-new-plugin/
├── pretix_my_new_plugin/
│   ├── __init__.py
│   └── apps.py            ← AppConfig + PretixPluginMeta required
└── setup.py               ← entry_points for pretix.plugin required
```

See `plugins/attendance_confirm_plugin/` for a fully working reference implementation.


## Repository structure

```
pretix-plugin-catalogue/
├── README.md
├── Dockerfile                        ← builds the bundle image
├── plugins.txt                       ← controls which plugins are included
├── .gitea/
│   └── workflows/
│       └── docker.yml                ← CI: build & push on tag
└── plugins/
    └── example-plugin/               ← reference plugin implementation
        ├── pretix_example_plugin/
        │   ├── __init__.py
        │   └── apps.py
        └── setup.py
```

## Credits

The plugins attendance_confirm_plugin and selective_export_plugin were developed by make IT social (https://makeitsocial.net/). Thanks!