pulp · gerrod3 · Apr 24, 2025 · Apr 3, 2025 · Apr 3, 2025 · Apr 3, 2025
diff --git a/README.md b/README.md
@@ -4,100 +4,8 @@ A developer environment for pulp based off of the [Pulp OCI Images](https://gith
 
 ## Getting started
 
-0. Install the `oci-env` python client.
-
-  ```bash
-  cd oci_env
-
-  # if pip3 isn't available, try pip. Python 3 is required for oci-env.
-  pip3 install -e client
-  ```
-
-1. Install podman or docker compose
-
-    - [docker-compose installation docs](https://docs.docker.com/compose/install/). 
-    - [podman-compose installation docs](https://github.com/containers/podman-compose#installation).
-
-2. Set up your directory with the following structure:
-
-    ```
-    .
-    ├── oci_env
-    ├── pulp-openapi-generator
-    ├── pulp_ansible
-    ├── pulp_container
-    ├── pulpcore
-    └── any_other_python_sources
-    ```
-
-    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` will look something like this:
-
-    ```
-    DEV_SOURCE_PATH=pulpcore:pulp_ansible
-
-    # this is set to podman by default.
-    COMPOSE_BINARY=docker
-    ```
-
-    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.
-      Example `COMPOSE_PROFILE=ha:galaxy_ng/ui`. This will use the the `ha` profile from `oci_env/profiles/`
-      and the `ui` profile from `galaxy_ng/profiles/`
-    - `PULP_<SETTING_NAME>`: set any setting.py value for your environment. Example: `PULP_GALAXY_REQUIRE_CONTENT_APPROVAL=False`
-
-4. Run the environment
-
-    ```bash
-    # 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 login 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](/docs/macos_troubleshooting_tips.md). 
-
-5. Teardown
-
-    To shut down the containers run `oci-env compose down`. Data in your system will be preserved when you restart the containers.
-
-    To delete the database run `oci-env compose down --volumes`. This will shut down the containers and delete all the container data in your system.
-
-## The oci-env CLI
-
-This CLI has all the functionality required to run the OCI Env developer environment. See `oci-env --help` for a list of supported commands.
-
-`oci-env` can either be run in the `oci_env/` root dir, or it can be executed from anywhere by setting the `OCI_ENV_PATH` environment variable.
-The path supplied to `OCI_ENV_PATH` is expected to be the `oci_env/` project root dir.
-
-## Resetting the DB
-
-The DB can be reset and migrations rerun with the `oci-env db reset` command. Alternatively, you could run the following:
-
-```bash
-oci-env compose down --volumes  # Shut down the containers and delete all the container data on your system
-oci-env compose up
-```
+A detailed guide on setting up the development environment is available
+[here](site:oci_env/docs/dev/tutorials/quickstart).
 
 ## Multiple environments
 

diff --git a/base/container_scripts/install_phelpers.sh b/base/container_scripts/install_phelpers.sh
@@ -43,7 +43,7 @@ pdbreset() {
 }
 _pdbreset_help="Reset the Pulp database"
 # can get away with not resetting terminal settings here since it gets reset in phelp
-_pdbreset_help="$_dbreset_help - `setterm -foreground red -bold on`THIS DESTROYS YOUR PULP DATA"
+_pdbreset_help="$_pdbreset_help - `setterm -foreground red -bold on`THIS DESTROYS YOUR PULP DATA"
 
 pclean() {
     pdbreset

diff --git a/staging_docs/dev/tutorials/quickstart.md b/staging_docs/dev/tutorials/quickstart.md
@@ -2,17 +2,22 @@
 
 Before we start, make sure you have at least one of the two installed:
 
-- [docker-compose installation docs](https://docs.docker.com/compose/install/). 
-- [podman-compose installation docs](https://github.com/containers/podman-compose#installation).
+- [docker compose installation docs](https://docs.docker.com/compose/install/)
+- [podman-compose installation docs](https://github.com/containers/podman-compose#installation) (version 1.2 is required)
+
+All mentioned repositories in this tutorial can be cloned from [here](https://github.com/pulp).
 
 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 can be run in the `oci_env/` root dir.
+- 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 the `oci_env/` project root dir.
+
 So let's get started.
 
-## 1. Install the `oci-env` python client.
+## 1. Install the `oci-env` python client
 
 ```bash
 cd oci_env
@@ -21,7 +26,7 @@ cd oci_env
 pip3 install -e client
 ```
 
-## 2. Set up your directory with the following structure:
+## 2. Set up your directories
 
 ```
 .
@@ -33,31 +38,32 @@ pip3 install -e client
 └── 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.
+## 3. Define your `compose.env` file
 
 `cp compose.env.example compose.env`
 
-A minimal `compose.env` will look something like this:
+A minimal `compose.env` with one optional ansible plugin will look something like this:
 
 ```
 DEV_SOURCE_PATH=pulpcore:pulp_ansible
-
-# this is set to podman by default.
-COMPOSE_BINARY=docker
 ```
 
 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.
-  Example `COMPOSE_PROFILE=ha:galaxy_ng/ui`. This will use the the `ha` profile from `oci_env/profiles/`
+  Example `COMPOSE_PROFILE=ha:galaxy_ng/ui`. This will use the `ha` profile from `oci_env/profiles/`
   and the `ui` profile from `galaxy_ng/profiles/`
+- `COMPOSE_BINARY`: program to use for compose. This can be either docker or podman, defaults to podman
 - `PULP_<SETTING_NAME>`: set any setting.py value for your environment. Example: `PULP_GALAXY_REQUIRE_CONTENT_APPROVAL=False`
 
 ## 4. Run the environment
@@ -67,13 +73,13 @@ include:
 oci-env compose build
 
 # start the service
-oci-env compose up 
+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 login with `admin`/`password` by default. E.g.:
+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.:
 
 ```bash
 http --auth admin:password get http://localhost:5001/pulp/api/v3/status/
@@ -82,20 +88,24 @@ 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.  
+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](site:oci_env/docs/dev/guides/macos_troubleshooting_tips.md). 
+In case you have problems with setup in macOS, check these
+[troubleshooting tips](site:oci_env/docs/dev/guides/troubleshooting/macos_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 aswell:
+Data in your system will be preserved when you restart it, or you can choose to tear down the volumes as well:
 
 ```bash
-# Preserve data
-oci-env compose up
+# tear down container but preserve data
+oci-env compose down
+
+# tear down container and delete data
+oci-env compose down --volumes
 
-# Tear down data
-oci-env compose down --volumes  # Shut down the containers and delete all the container data on your system
-oci-env db reset # alias
+# or reset data only and rerun migrations
+oci-env db reset
 ```