Skip to content

update installation instructions #675

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

update installation instructions #675

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2941ca6
update README
furlongm Apr 18, 2025
d01f0eb
add errata source options to config file
furlongm Apr 18, 2025
f998d6f
update installation instructions
furlongm Apr 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 6 additions & 3 deletions BUILD.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,21 +5,24 @@ vim VERSION.txt # modify version
git add VERSION.txt
version=$(<VERSION.txt)
git commit -m "Release v${version}"
git tag v${version}
```

# Build DEB package

```shell
sudo apt -y install python3-setuptools debhelper dh-exec dh-python git-buildpackage
gbp dch --commit
gbp buildpackage -uc -us
version=$(<VERSION.txt)
gbp dch --commit --new-version=${version}-1 --release --distribution=stable
git tag v${version}
gbp buildpackage -uc -us --git-upstream-tree=main
```

# Build RPM packages

```shell
sudo dnf -y install rpm-build git python3-setuptools
version=$(<VERSION.txt)
git tag v${version}
python3 setup.py bdist_rpm --python=/usr/bin/python3
rpmbuild -bb patchman-client.spec
```
198 changes: 131 additions & 67 deletions INSTALL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,19 +4,19 @@ The default installation uses sqlite3 for the django database. To configure
mysql or postgresql instead, see the database configuration section.


## Supported Install Options
- [Ubuntu 22.04](#ubuntu-2204-jammy)
## Supported Server Installation Options
- [Ubuntu 24.04](#ubuntu-2404-noble)
- [Debian 12](#debian-12-bookworm)
- [CentOS 9](#centos-9)
- [Rocky 10](#rocky-10)
- [virtualenv + pip](#virtualenv--pip)
- [Source](#source)


### Ubuntu 22.04 (jammy)
### Ubuntu 24.04 (noble)

```shell
curl -sS https://repo.openbytes.ie/openbytes.gpg > /usr/share/keyrings/openbytes.gpg
echo "deb [signed-by=/usr/share/keyrings/openbytes.gpg] https://repo.openbytes.ie/patchman/ubuntu jammy main" > /etc/apt/sources.list.d/patchman.list
echo "deb [signed-by=/usr/share/keyrings/openbytes.gpg] https://repo.openbytes.ie/patchman/ubuntu noble main" > /etc/apt/sources.list.d/patchman.list
apt update
apt -y install python3-patchman patchman-client
patchman-manage createsuperuser
Expand All @@ -26,22 +26,23 @@ patchman-manage createsuperuser

```shell
curl -sS https://repo.openbytes.ie/openbytes.gpg > /usr/share/keyrings/openbytes.gpg
echo "deb [signed-by=/usr/share/keyrings/openbytes.gpg] https://repo.openbytes.ie/patchman/debian bookworm main" > /etc/apt/sources.list.d/patchman.list
echo "deb [signed-by=/usr/share/keyrings/openbytes.gpg] https://repo.openbytes.ie/patchman/debian bookworm-backports main" > /etc/apt/sources.list.d/patchman.list
echo "deb http://deb.debian.org/debian bookworm-backports main" > /etc/apt/sources.list.d/backports.list
apt update
apt -y install python3-patchman patchman-client
apt -y install -t bookworm-backports python3-patchman patchman-client
patchman-manage createsuperuser
```

### CentOS 9
### Rocky 10

This also applies to Rocky/Alma/RHEL
This also applies to Alma, RHEL, etc.

```shell
curl -sS https://repo.openbytes.ie/openbytes.gpg > /etc/pki/rpm-gpg/RPM-GPG-KEY-openbytes
cat <<EOF >> /etc/yum.repos.d/openbytes.repo
[openbytes]
name=openbytes
baseurl=https://repo.openbytes.ie/patchman/el9
baseurl=https://repo.openbytes.ie/patchman/el10
enabled=1
gpgcheck=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-openbytes
Expand All @@ -60,7 +61,7 @@ TBD - not working yet

```shell
apt -y install gcc libxml2-dev libxslt1-dev virtualenv python3-dev zlib1g-dev # (debian/ubuntu)
dnf -y install gcc libxml2-devel libxslt-devel python3-virtualenv # (centos/rocky/alma)
dnf -y install gcc libxml2-devel libxslt-devel python3-virtualenv # (rocky/alma/redhat)
mkdir /srv/patchman
cd /srv/patchman
python3 -m venv .venv
Expand All @@ -74,7 +75,7 @@ gunicorn patchman.wsgi -b 0.0.0.0:80

### Source

#### Ubuntu 22.04 (jammy)
#### Ubuntu 24.04 (noble)

1. Install dependencies

Expand Down Expand Up @@ -107,9 +108,9 @@ cp /srv/patchman/etc/patchman/local_settings.py /etc/patchman/

# Configuration

## Patchman Settings
## Patchman Server Settings

Modify `/etc/patchman/local_settings.py` to configure patchman.
Modify `/etc/patchman/local_settings.py` to configure the patchman server.

If installing from source or using virtualenv, the following settings should
be configured:
Expand All @@ -119,28 +120,32 @@ be configured:
* STATIC_ROOT - should point to `/srv/patchman/run/static` if installing from
source

## Patchman-client Settings
The default settings for errata downloading may include operating systems that
are not relevant to a given deployment. If this is the case, modify the
`ERRATA_OS_UPDATES` setting in `/etc/patchman/local_settings.py`. Further
distribution-specific settings are also available to only download errata
for specific versions/codenames.

## Patchman Client Settings

The client comes with a default configuration. This configuration will attempt to upload the reports to a server at *patchman.example.com*. This configuration needs to be updated to connect to your own patchman installation.
The client comes with a default configuration that will attempt to upload the
reports to a server at *patchman.example.com*. This configuration needs to be
updated to connect to the correct patchman server.

In `/etc/patchman/patchman-client.conf`, look for the following line(s):
Change the following lines in `/etc/patchman/patchman-client.conf`:

```
# Patchman server
server=https://patchman.example.com
server=https://patchman.example.com

# Options to curl
curl_options="--insecure --connect-timeout 60 --max-time 300"

...
```
* *server* needs to point the URL where your patchman server
is running
* *--insecure* in the curl_options tells the client to ignore certificates, if you set them up correctly and are using patchman with "https:/...", you could remove this flag to increase security




* *server* needs to point the URL where the local patchman server is running
* *--insecure* in the curl options tells the client to ignore certificates.
If the patchman server is set up correctly with certificates this flag can
be removed to increase security.

## Configure Database

Expand All @@ -151,10 +156,13 @@ production deployments. MySQL or PostgreSQL are better choices.

To configure the sqlite database backend:

1. Create the database directory specified in the settings file:
1. Create the database directory specified in the settings file, touch the
database file and set the journal mode to WAL:

```shell
mkdir -p /var/lib/patchman/db
touch /var/lib/patchman/db/patchman.db
sqlite3 /var/lib/patchman/db/patchman.db 'PRAGMA journal_mode=WAL;'
```

2. Modify `/etc/patchman/local_settings.py` as follows:
Expand All @@ -163,7 +171,7 @@ mkdir -p /var/lib/patchman/db
DATABASES = {
'default': {
'ENGINE': 'django.db.backends.sqlite3',
'NAME': '/var/lib/patchman/db/patchman.db'
'NAME': '/var/lib/patchman/db/patchman.db',
}
}
```
Expand Down Expand Up @@ -199,16 +207,16 @@ Query OK, 0 rows affected (0.00 sec)

```
DATABASES = {
'default': {
'ENGINE': 'django.db.backends.mysql',
'NAME': 'patchman',
'USER': 'patchman',
'PASSWORD': 'changeme',
'HOST': '',
'PORT': '',
'STORAGE_ENGINE': 'INNODB',
'CHARSET' : 'utf8'
}
'default': {
'ENGINE': 'django.db.backends.mysql',
'NAME': 'patchman',
'USER': 'patchman',
'PASSWORD': 'changeme',
'HOST': '',
'PORT': '',
'STORAGE_ENGINE': 'INNODB',
'CHARSET': 'utf8',
}
}
```

Expand Down Expand Up @@ -250,15 +258,15 @@ GRANT

```
DATABASES = {
'default': {
'ENGINE': 'django.db.backends.postgresql_psycopg2',
'NAME': 'patchman',
'USER': 'patchman',
'PASSWORD': 'changeme',
'HOST': '127.0.0.1',
'PORT': '',
'CHARSET' : 'utf8'
}
'default': {
'ENGINE': 'django.db.backends.postgresql_psycopg2',
'NAME': 'patchman',
'USER': 'patchman',
'PASSWORD': 'changeme',
'HOST': '127.0.0.1',
'PORT': '',
'CHARSET': 'utf8',
}
}
```

Expand All @@ -273,8 +281,7 @@ After configuring a database backend, the django database should be synced:
collect static files:

```shell
patchman-manage makemigrations
patchman-manage migrate --run-syncdb --fake-initial
patchman-manage migrate --run-syncdb
patchman-manage createsuperuser
patchman-manage collectstatic
```
Expand All @@ -285,6 +292,27 @@ N.B. To run patchman-manage when installing from source, run `./manage.py`
2. Restart the web server after syncing the database.


### Migrate from sqlite to another database backend

The prebuilt package installations use sqlite as the default database backend,
but this is not recommended in production. To migrate from sqlite to another
database backend, use the following procedure:

1. Dump the sqlite database to a json file

```shell
patchman-manage dumpdata --exclude packages.Packagestring -e contenttypes -e auth.Permission --natural-foreign --natural-primary --indent 4 > patchman-db.json
```

2. Create the new database and add the new database settings to `/etc/patchman/local_settings.py`

3. Sync the new database and load the existing data:

```
patchman-manage migrate --run-syncdb
patchman-manage loaddata patchman-db.json
```

## Configure Web Server

### Apache
Expand All @@ -301,7 +329,7 @@ a2enconf patchman

```shell
vi /etc/apache2/conf-available/patchman.conf
service apache2 reload
systemctl reload apache2
```

3. If installing from source, allow apache access to the settings and to the sqlite db:
Expand All @@ -321,9 +349,10 @@ The django interface should be available at http://127.0.0.1/patchman/

#### Daily cronjob on patchman server

A daily cronjob on the patchman server should be run to process reports,
perform database maintenance, check for upstream updates, and find updates for
clients.
A daily cronjob on the patchman server can be run to process reports, perform
database maintenance, check for upstream updates, and find updates for clients.
Alternatively, run celery as outlined below for finer granularity over the
timing of these tasks and for increased concurrency.

```
patchman -a
Expand All @@ -337,16 +366,17 @@ patchman-client

### Celery

Install Celery for realtime processing of reports from clients:
Install Celery for realtime processing of reports from clients and for periodic
maintenance tasks. The celery configuation file is in `/etc/patchman/celery.conf`

#### Ubuntu / Debian

```shell
apt -y install python3-celery redis python3-redis python-celery-common
C_FORCE_ROOT=1 celery -b redis://127.0.0.1:6379/0 -A patchman worker -l INFO -E
/usr/bin/celery --broker redis://127.0.0.1:6379/0 --app patchman worker --loglevel info --beat --scheduler django_celery_beat.schedulers:DatabaseScheduler --task-events --pool threads
```

#### CentOS / Rocky / Alma
#### Rocky / Alma / RHEL

Currently waiting on https://bugzilla.redhat.com/show_bug.cgi?id=2032543

Expand All @@ -355,35 +385,69 @@ dnf -y install python3-celery redis python3-redis
systemctl restart redis
semanage port -a -t http_port_t -p tcp 6379
setsebool -P httpd_can_network_connect 1
C_FORCE_ROOT=1 celery -b redis://127.0.0.1:6379/0 -A patchman worker -l INFO -E
/usr/bin/celery --broker redis://127.0.0.1:6379/0 --app patchman worker --loglevel info --beat --scheduler django_celery_beat.schedulers:DatabaseScheduler --task-events --pool threads
```

Add the last command to an initscript (e.g. /etc/rc.local) to make celery
persistent over reboot.
#### Persistence

There is a systemd unit file for celery to make the service persistent over reboot:

Enable celery by adding `USE_ASYNC_PROCESSING = True` to `/etc/patchman/local_settings.py`
`etc/systemd/system/patchman-celery.service`

### Memcached
If installing from prebuilt packages, this should be enabled by default.

Memcached can optionally be run to reduce the load on the server.

### Caching

Memcached or Redis can optionally be run to reduce the load on the server.
Note that caching may result in the web interface showing results that are
out of date with the database, so this is disabled by default.


#### Redis

Install Redis:

```shell
apt -y install redis python3-redis # (debian/ubuntu)
dnf -y install redis python3-redis # (rocky/alma/redhat)
systemctl restart redis/redis-server
```

and add the following to `/etc/patchman/local_settings.py`

```
CACHES = {
'default': {
'BACKEND': 'django.core.cache.backends.redis.RedisCache',
'LOCATION': 'redis://127.0.0.1:6379',
'TIMEOUT': 30,
}
}
```

#### Memcacached

Install Memcached

```shell
apt -y install memcached python3-pymemcache # (debian/ubuntu)
dnf -y install memcached python3-pymemcache # (centos/rocky/alma)
dnf -y install memcached python3-pymemcache # (rocky/alma/redhat)
systemctl restart memcached
```

and add the following to `/etc/patchman/local_settings.py`

```
CACHES = {
'default': {
'BACKEND': 'django.core.cache.backends.memcached.PyMemcacheCache',
'LOCATION': '127.0.0.1:11211',
'default': {
'BACKEND': 'django.core.cache.backends.memcached.PyMemcacheCache',
'LOCATION': '127.0.0.1:11211',
'TIMEOUT': 30,
'OPTIONS': {
'ignore_exc': True,
},
}
}
}
```

Expand Down
Loading