Instructions¶
Supported Platforms¶
Pulp should work on any operating system that can provide a Python 3.6+ runtime environment and the supporting dependencies e.g. a database. Pulp has been demonstrated to work on Ubuntu, Debian, Fedora, CentOS, and Mac OSX.
Note
Pulp 3 currently does not have an AppArmor Profile. Until then, any environment you run Pulp 3 in must have AppArmor either permissive or disabled. There are risks associated with this decision. See your distribution’s docs for more details
Ansible Installation (Recommended)¶
The Pulp 3 Ansible Installer is a collection of Ansible roles designed to automate the installation of Pulp and any content plugins that you want.
You can customize and configure your Pulp deployment through the Ansible variables for each role.
For comprehensive and up-to-date instructions about using the Pulp Ansible installer, see the Pulp Installer documentation.
PyPI Installation¶
(Optional) Create a user account & group for Pulp 3 to run under, rather than using root. The following values are recommended:
name: pulp
shell: The path to the nologin executable
home:
MEDIA_ROOT
system account: yes
create corresponding private group: yes
Install python3.6(+) and pip.
Create a pulp venv:
$ python3 -m venv pulpvenv $ source pulpvenv/bin/activate
Note
On some operating systems you may need to install a package which provides the venv
module.
For example, on Ubuntu or Debian you need to run:
$ sudo apt-get install python3-venv
Install Pulp using pip:
$ pip install pulpcore
Note
To install from source, clone git repositories and do a local, editable pip installation:
$ git clone https://github.com/pulp/pulpcore.git
$ pip install -e ./pulpcore[postgres]
Configure Pulp by following the configuration instructions.
Set
SECRET_KEY
andCONTENT_ORIGIN
according to the settings.Create
MEDIA_ROOT
andWORKING_DIRECTORY
with the prescribed permissions proposed in the settings.Go through the Database Setup, Redis, and Systemd sections.
Run Django Migrations:
$ pulpcore-manager migrate --noinput $ pulpcore-manager reset-admin-password --password << YOUR SECRET HERE >>
Note
The pulpcore-manager
command is manage.py
configured with the
DJANGO_SETTINGS_MODULE="pulpcore.app.settings"
. You can use it anywhere you would normally
use manage.py
.
Warning
You should never attempt to create new migrations via the pulpcore-manager makemigrations
.
In case, new migrations would be needed, please file a bug against the respective plugin.
How to File an Issue
Note
In place of using the systemd unit files provided in the systemd-setup section, you can run the commands yourself inside of a shell. This is fine for development but not recommended in production:
$ /path/to/python/bin/pulpcore-worker --resource-manager
$ /path/to/python/bin/pulpcore-worker
Collect Static Media for live docs and browsable API:
$ pulpcore-manager collectstatic --noinput
Run Pulp:
$ pulp-content # The Pulp Content service (listening on port 24816) $ pulpcore-manager runserver 24817 # The Pulp API service
Database Setup¶
You must provide a PostgreSQL database for Pulp to use. At this time, Pulp 3.0 will only work with PostgreSQL.
PostgreSQL¶
Installation package considerations¶
To install PostgreSQL, refer to the package manager or the PostgreSQL install docs. Oftentimes, you can also find better installation instructions for your particular operating system from third-parties such as Digital Ocean.
On Ubuntu and Debian, the package to install is named postgresql
. On Fedora and CentOS, the package
is named postgresql-server
.
User and database configuration¶
The default PostgreSQL user and database name in the provided server.yaml file is pulp
. Unless you plan to
customize the configuration of your Pulp installation, you will need to create this user with the proper permissions
and also create the pulp
database owned by the pulp
user. If you do choose to customize your installation,
the database options can be configured in the DATABASES section of your server.yaml settings file.
See the Django database settings documentation
for more information on setting the DATABASES values in server.yaml.
UTF-8 encoding¶
You must configure PostgreSQL to use UTF-8 character set encoding.
Post-installation setup¶
After installing and configuring PostgreSQL, you should configure it to start at boot, and then start it:
$ sudo systemctl enable postgresql
$ sudo systemctl start postgresql
Redis¶
The Pulp tasking system runs on top of Redis. This can be on a different host or the same host that Pulp is running on.
To install Redis, refer to your package manager or the Redis download docs.
For Fedora, CentOS, Debian, and Ubuntu, the package to install is named redis
.
After installing and configuring Redis, you should configure it to start at boot and start it:
$ sudo systemctl enable redis
$ sudo systemctl start redis
Systemd¶
To run the four Pulp services, systemd files needs to be created in /usr/lib/systemd/system/. The
Pulp 3 Ansible Installer makes these for you, but you
can also configure them by hand from the templates below. Custom configuration can be applied using
the Environment
option with various Pulp settings.
Make a
pulpcore-content.service
file for the pulpcore-content service which serves Pulp content to clients. We recommend starting with the pulpcore-content template and setting the variables according to the pulpcore_content config variables documentationMake a
pulpcore-api.service
file for the pulpcore-api service which serves the Pulp REST API. We recommend starting with the pulpcore-api template and setting the variables according to the pulpcore-api config variables documentationMake a
pulpcore-worker@.service
file for the pulpcore-worker processes which allows you to manage one or more workers. We recommend starting with the pulpcore-worker template and setting the variables according to the pulp_workers config variables documentationMake a
pulpcore-resource-manager.service
file which can manage one pulpcore-resource-manager process. We recommend starting with the pulpcore-resource-manager template and setting the variables according to the pulp_resource_manager config variables documentation
These services can then be started by running:
sudo systemctl start pulpcore-resource-manager
sudo systemctl start pulpcore-content
sudo systemctl start pulpcore-api
sudo systemctl start pulpcore-worker@1
sudo systemctl start pulpcore-worker@2
SSL¶
Users should configure HTTPS communication between clients and the reverse proxy that is in front of pulp services like pulpcore-api and pulpcore-content. The Pulp Installer provides three different options for configuring SSL certificates for nginx and httpd reverse proxies.
By default, the installer will generate a new Certificate Authority and use it to sign an SSL certificate. In this case, the Pulp administrator will need to distribute the Certificate Authority certificate or the SSL certificate to all clients that wish to communicate with Pulp. Clients will need to import one of these certificates to their system CA trust store.
The default location for the CA certificate is
/etc/pulp/certs/root.crt
. The default location for the SSL certificate is/etc/pulp/certs/pulp_webserver.crt
.If you already have an SSL Cerificate that you want to be used by the reverse proxy to encrypt communication with clients, the Pulp Installer supports providing a path for
pulp_webserver_tls_cert
andpulp_webserver_tls_key
. The administrator is still responsible for making sure that clients trust the Certificate Authority that signed the SSL certificate.The Pulp Installer also supports using services that use the ACME protocol, e.g. https://letsencrypt.org/, to generate trusted SSL certificates. See the Pulp Installer documentation for instructions and an example playbook.