misp-docker/README.md

112 lines
6.1 KiB
Markdown
Raw Normal View History

2023-12-05 12:32:40 +01:00
# MISP Docker images
2020-01-29 15:30:26 +01:00
2023-12-07 23:25:21 +01:00
[![Build Status](https://img.shields.io/github/actions/workflow/status/MISP/misp-docker/release-latest.yml)](https://github.com/orgs/MISP/packages)
2020-02-27 15:49:29 +01:00
[![Gitter chat](https://badges.gitter.im/gitterHQ/gitter.png)](https://gitter.im/MISP/Docker)
2020-01-29 15:30:26 +01:00
2023-12-07 13:38:04 +01:00
A production ready Docker MISP image (formerly hosted at https://github.com/ostefano/docker-misp, now deprecated) loosely based on CoolAcid and DSCO builds, with nearly all logic rewritten and verified for correctness and portability.
2023-12-05 13:34:46 +01:00
Notable features:
2023-12-07 23:25:21 +01:00
- MISP and MISP modules are split into two different Docker images, `misp-core` and `misp-modules`
2023-12-07 13:38:04 +01:00
- Docker images are pushed regularly, no build required
- Lightweigth Docker images by using multiple build stages and a slim parent image
- Rely on off the shelf Docker images for Exim4, Redis, and MariaDB
- Cron jobs run updates, pushes, and pulls
2022-12-07 09:52:49 +01:00
- Fix supervisord process control (processes are correctly terminated upon reload)
- Fix schema update by making it completely offline (no user interaction required)
- Fix enforcement of permissions
- Fix MISP modules loading of faup library
- Fix MISP modules loading of gl library
2023-12-07 13:50:46 +01:00
- Add support for new background job [system](https://github.com/MISP/MISP/blob/2.4/docs/background-jobs-migration-guide.md)
2022-12-07 09:52:49 +01:00
- Add support for building specific MISP and MISP-modules commits
2023-12-07 13:38:04 +01:00
- Add automatic configuration of syncservers (see `configure_misp.sh`)
2023-12-05 13:34:46 +01:00
- Add automatic configuration of authentication keys (see `configure_misp.sh`)
2023-12-07 13:38:04 +01:00
- Add direct push of docker images to GitHub Packages
- Consolidated `docker-compose.yml` file
- Workardound VirtioFS bug when running Docker Desktop for Mac
- ... and many others
2020-01-29 16:26:54 +01:00
2023-12-05 13:34:46 +01:00
The underlying spirit of this project is to allow "repeatable deployments", and all pull requests in this direction will be merged post-haste.
2020-02-12 15:18:32 +01:00
## Getting Started
2023-11-03 10:57:58 +01:00
- Copy the `template.env` to `.env`
- Customize `.env` based on your needs (optional step)
2022-09-03 13:59:35 +02:00
2023-11-03 10:57:58 +01:00
### Run
2020-02-12 15:18:32 +01:00
- `docker-compose pull` if you want to use pre-built images or `docker-compose build` if you want to build your own (see the `Troubleshooting` section in case of errors)
2020-02-12 15:18:32 +01:00
- `docker-compose up`
- Login to `https://localhost`
2020-02-12 15:23:47 +01:00
- User: `admin@admin.test`
- Password: `admin`
2020-02-12 15:27:48 +01:00
2023-12-07 13:38:04 +01:00
Keeping the image up-to-date with upstream should be as simple as running `docker-compose pull`.
2023-11-03 10:57:58 +01:00
### Configuration
2023-11-03 10:57:58 +01:00
The `docker-compose.yml` file allows further configuration settings:
```
"MYSQL_HOST=db"
"MYSQL_USER=misp"
"MYSQL_PASSWORD=example" # NOTE: This should be AlphaNum with no Special Chars. Otherwise, edit config files after first run.
"MYSQL_DATABASE=misp"
"MISP_MODULES_FQDN=http://misp-modules" # Set the MISP Modules FQDN, used for Enrichment_services_url/Import_services_url/Export_services_url
"WORKERS=1" # Legacy variable controlling the number of parallel workers (use variables below instead)
"NUM_WORKERS_DEFAULT=5" # To set the number of default workers
"NUM_WORKERS_PRIO=5" # To set the number of prio workers
"NUM_WORKERS_EMAIL=5" # To set the number of email workers
"NUM_WORKERS_UPDATE=1" # To set the number of update workers
"NUM_WORKERS_CACHE=5" # To set the number of cache workers
```
2020-02-28 01:53:47 +01:00
2023-11-03 10:57:58 +01:00
New options are added on a regular basis.
2020-02-12 15:18:32 +01:00
### Production
2023-12-07 23:25:21 +01:00
- It is recommended to specify the build you want run by editing `docker-compose.yml` (see here for the list of available tags https://github.com/orgs/MISP/packages)
2020-02-25 03:09:08 +01:00
- Directory volume mount SSL Certs `./ssl`: `/etc/ssl/certs`
2020-02-24 18:11:32 +01:00
- Certificate File: `cert.pem`
- Certificate Key File: `key.pem`
2021-04-07 16:46:59 +02:00
- CA File for Cert Authentication (optional) `ca.pem`
2020-02-12 15:18:32 +01:00
- Additional directory volume mounts:
- `./configs`: `/var/www/MISP/app/Config/`
- `./logs`: `/var/www/MISP/app/tmp/logs/`
- `./files`: `/var/www/MISP/app/files/`
- `./gnupg`: `/var/www/MISP/.gnupg/`
- If you need to automatically run additional steps each time the container starts, create a new file `files/customize_misp.sh`, and replace the variable `${CUSTOM_PATH}` inside `docker-compose.yml` with its parent path.
2020-02-12 15:18:32 +01:00
## Installing custom root CA certificates
Custom root CA certificates can be mounted under `/usr/local/share/ca-certificates` and will be installed during the `misp-core` container start.
**Note:** It is important to have the .crt extension on the file, otherwise it will not be processed.
```yaml
misp-core:
# ...
volumes:
- "./configs/:/var/www/MISP/app/Config/"
- "./logs/:/var/www/MISP/app/tmp/logs/"
- "./files/:/var/www/MISP/app/files/"
- "./ssl/:/etc/nginx/certs/"
- "./gnupg/:/var/www/MISP/.gnupg/"
# customize by replacing ${CUSTOM_PATH} with a path containing 'files/customize_misp.sh'
# - "${CUSTOM_PATH}/:/custom/"
# mount custom ca root certificates
- "./rootca.pem:/usr/local/share/ca-certificates/rootca.crt"
```
2023-12-07 13:38:04 +01:00
## Troubleshooting
2023-11-03 10:57:58 +01:00
2023-12-07 13:38:04 +01:00
- Make sure you run a fairly recent version of Docker and Docker Compose (if in doubt, update following the steps outlined in https://docs.docker.com/engine/install/ubuntu/)
- Some Linux distributions provide a recent version of Docker but a legacy version of Docker Compose, so you can try running `docker compose` instead of `docker-compose`
2023-12-07 13:38:04 +01:00
- Make sure you are not running an old image or container; when in doubt run `docker system prune --volumes` and clone this repository into an empty directory
2020-11-04 00:50:11 +01:00
2023-12-07 13:38:04 +01:00
## Versioning
2020-02-12 15:18:32 +01:00
2023-12-07 23:25:21 +01:00
A GitHub Action builds both `misp-core` and `misp-modules` images automatically and pushes them to the [GitHub Package registry](https://github.com/orgs/MISP/packages). We do not use tags inside the repository; instead we tag images as they are pushed to the registry. For each build, `misp-core` and `misp-modules` images are tagged as follows:
- `misp-core:${commit-sha1}[0:7]` and `misp-modules:${commit-sha1}[0:7]` where `${commit-sha1}` is the commit hash triggering the build
- `misp-core:latest` and `misp-modules:latest` in order to track the latest builds available
2023-12-08 09:45:49 +01:00
- `misp-core:${CORE_TAG}` and `misp-modules:${MODULES_TAG}` reflecting the underlying version of MISP and MISP modules (as specified inside the `template.env` file at build time)