Getting started¶
Before we start, make sure you have at least one of the two installed:
- docker compose installation docs
- podman-compose installation docs (version 1.2 is required)
All mentioned repositories in this tutorial can be cloned from here.
Also, here are some useful things about the CLI:
- It has all the functionality required to run the OCI Env developer environment.
See
oci-env --help
for a list of supported commands. - It contains "p commands" to ease the management of pulp component services, such as the workers
(API, content and tasking) and the PostgreSQL DB. See
oci-env phelp
for a list of supported commands. - It can be run in the
oci_env/
root dir. - It can be executed from anywhere by setting the
OCI_ENV_PATH
environment variable to theoci_env/
project root dir.
So let's get started.
1. Install the oci-env
python client¶
cd oci_env
# if pip3 isn't available, try pip. Python 3 is required for oci-env.
pip3 install -e client
2. Set up your directories¶
.
├── oci_env
├── pulp-openapi-generator
├── pulp_ansible
├── pulp_container
├── pulpcore
└── any_other_python_sources
The minimal requirements are oci_env
and pulpcore
. pulp-openapi-generator
is necessary for running tests.
pulp_ansible
and pulp_container
serve as examples of optional plugins.
The OCI env project should be in the same directory as any pulp plugins you wish to run.
Note, the /src/
folder in the container is the parent folder containing the oci_env
and all
plugin checkouts on the container host.
3. Define your compose.env
file¶
cp compose.env.example compose.env
A minimal compose.env
with one optional ansible plugin will look something like this:
DEV_SOURCE_PATH=pulpcore:pulp_ansible
In this example, ../pulpcore
and ../pulp_ansible
will be installed from source. Other settings
include:
COMPOSE_PROFILE
: this is used to define environments with extra services running. This could be used to launch a UI, set up an authentication provider service or configure an object store. ExampleCOMPOSE_PROFILE=ha:galaxy_ng/ui
. This will use theha
profile fromoci_env/profiles/
and theui
profile fromgalaxy_ng/profiles/
COMPOSE_BINARY
: program to use for compose. This can be either docker or podman, defaults to podmanPULP_<SETTING_NAME>
: set any settings.py value for your environment. Example:PULP_GALAXY_REQUIRE_CONTENT_APPROVAL=False
4. Run the environment¶
# build the images
oci-env compose build
# start the service
oci-env compose up
The oci-env compose
command accepts all the same arguments as podman-compose
or docker compose
By default, the API will be served from http://localhost:5001/pulp/api/v3/
.
You can log in with admin
/password
by default. E.g.:
http --auth admin:password get http://localhost:5001/pulp/api/v3/status/
The api will reload anytime changes are made to any of the DEV_SOURCE_PATH
projects.
oci-env compose
accepts all of the arguments that docker and podman compose take.
You can also launch the environment in the background with oci-env compose up -d
and access the logs with oci-env compose logs -f
if you don't want to run it in the foreground.
In case you have problems with setup in macOS, check these troubleshooting tips.
5. Teardown¶
When you are done, you can tear down your container. Data in your system will be preserved when you restart it, or you can choose to tear down the volumes as well:
# tear down container but preserve data
oci-env compose down
# tear down container and delete data
oci-env compose down --volumes
# or reset data only and rerun migrations
oci-env db reset