misp-modules/docs/install.md

IMPORTANT NOTE: we will soon be publishing `misp-modules` on PyPI.


## Install from pip

It is strongly recommended to use a virtual environment (see here for instructions https://docs.python.org/3/tutorial/venv.html).

Once the virtual environment is loaded just use the command:

~~~~bash
pip install misp-modules
~~~~


## Install from cloned repository

In this case the only requirement is to install `poetry`. Normally you just need to run `pip install poetry`, but see here for more alternatives https://python-poetry.org/docs/#installation.

Once `poetry` is installed, you can clone the repository and install `misp-modules` as follows:

~~~~bash
git clone https://github.com/MISP/misp-modules.git && cd misp-modules
git submodule update --init
poetry install
~~~~

Note that the dependencies will require a number of system packages installed. On Ubuntu these packages are `libpoppler-cpp-dev`, `libzbar0`, and `tesseract-ocr`. For an updated list, check the github action used to test the build inside `.github/workflows`.


## Install the systemd unit

To run `misp-modules` as a service on a distribution based on systemd, you need to create the unit as follows and store it in a file `/etc/systemd/system/misp-modules.service`:

~~~~bash
[Unit]
Description=MISP modules

[Service]
Type=simple
User=apache
Group=apache
ExecStart='/path/to/venv/bin/misp-modules -l 127.0.0.1 -s'
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
~~~~

Then, enable the misp-modules service and start it:
~~~~bash
systemctl daemon-reload
systemctl enable --now misp-modules
~~~~


## Run the tests

To run tests you need to install misp-modules from the cloned repository, run the server, and then run the tests. You can do all these step with `poetry`.

~~~~bash
poetry install
poetry run misp-modules
~~~~

And in another terminal:

~~~~bash
poetry run pytest
~~~~


## Build the documentation

To build the documentation you can use the provided `Makefile`.
Inside you will find three targets:

- `generate_docs`: install the depdendency and generate the documentation.

- `generate_docs`: build the documentation using `mkdocs`.

- `deploy`: deploy the documentation using `mkdocs gh-deploy`.

- `test-docs`: run a local server exposing the newly built documentation.

Note that you can either run the targets using `poetry` (default), or using the `squidfunk/mkdocs-material` by setting the environment variable `USE_DOCKER=true`.


## Run MISP modules

If you installed it using pip, you just need to execute the command `misp-modules` (source the virtual environment a second time to update the search paths). If you installed it from the cloned repository, just use poetry, i.e., `poetry run misp-modules`.


## Run MISP modules in Docker

You can find an up-to-date container image and related documentation at the following repository:m https://github.com/MISP/misp-docker 


## Install misp-module on an offline instance

### If `misp-modules` is available on PyPI

Once `misp-modules` is available on PyPI, you can just download all the necessary packages:

~~~~bash
mkdir wheels
pip wheel misp-modules --no-cache-dir -w ./wheels
~~~~

Move the `wheels` directory to the target system, and install them there:

~~~~bash
pip install --no-cache-dir --use-deprecated=legacy-resolver /wheels/*.whl
~~~~

Once again, using a virtual environment is recommended.

### If `misp-modules` is not available on PyPI

You have two choices, the first approach uses `poetry export` to export the entire virtual environment so you can copy and run it on the target system; the second one uses `poetry bundle` to export a `requirements.txt` file.

#### Using `poetry bundle`

This is quite straightforward but it assumes your target system is relatively similar (same distribution, architecture, libaries).

~~~~bash
poetry install
poetry self add poetry-plugin-bundle
poetry bundle venv /destination/path/
~~~~

#### Using `poetry export`

This is a bit more convoluted and it is similar to how you would install `misp-modules` on an offline instance.

Just follow those instructions but replace the package `misp-modules` with `-r requirements.txt`.

Before doing so you need to generate the `requirements.txt` file. Due to the fact we are still supporting Python 3.8 and that Poetry still has some limitations (soon to be resolved) you need to need to replace the line `python = ">=3.8.*,<3.13"` inside `pyproject.toml` with your exact version (just run `python --version`).

Once you have done that, run the following commands to generate your very own `requirements.txt`.

~~~~bash
poetry lock
poetry install
poetry self add poetry-plugin-export
poetry export --without-hashes -f requirements.txt -o requirements.txt
~~~~