Running in Docker

It is recommended to run LSO inside a Docker container, as this helps separate installed dependencies for your Ansible playbooks and other scripts from the rest of the host system. For this, it is not necessary to clone any repository. However, we recommend you prepare the following files:

• requirements.txt - Python requirements
• ansible-galaxy-requirements.txt - Ansible roles and collections
• .env.develop, .env.test, etc… - Runtime variables for different environments
• Dockerfile - For building your image, explained below
• compose.yaml - For deploying your Docker image, explained below

Building an image

To build your own Docker image, you can use the following example file:

FROM python:3.12-alpine

WORKDIR /app

# Copy in requirements files, if needed
# These could be for Ansible Galaxy, Poetry, or a requirements.txt file
COPY ./requirements.txt ./requirements.txt
COPY ./ansible-galaxy-requirements.yaml ./ansible-galaxy-requirements.yaml

# Install required system packages
RUN apk add --update --no-cache gcc libc-dev libffi-dev openssh

# Install the LSO python package, and additional requirements
RUN pip install orchestrator-lso=="2.4.5"
RUN pip install -r requirements.txt

# Install required Ansible Galaxy roles and collections
RUN ansible-galaxy install \
                   -r ansible-galaxy-requirements.yaml \
                   -p /app/gap/ansible
RUN ansible-galaxy collection install \
                   -r ansible-galaxy-requirements.yaml \
                   -p /app/gap/ansible

EXPOSE 8000
ENTRYPOINT []
CMD ["python", "-m",  "uvicorn", "lso.app:app", "--host", "0.0.0.0", "--port", "8000"]

This will install:

• Any dependent system packages like gcc or libc-dev,
• the orchestrator-lso python package,
• further Python dependencies as defined in a requirements.txt file, and
• required Ansible roles and collections defined in ansible-galaxy-requirements.yaml.

To build the image, run something along the lines of:

docker build -t my-special-lso:dev .

More documentation for building, tagging, and publishing Docker images is available at the getting started or Docker Build reference pages.

Deploying

Using Docker Compose, your newly built Docker image can be deployed using this example snippet:

---
services:
  lso:
    image: my-lso:latest
    env_file: 
      .env  # Load default environment variables from the .env file
    volumes:
      - "/home/user/ansible_inventory:/opt/ansible_inventory:ro"
      - "~/.ssh/id_ed25519.pub:/root/.ssh/id_ed25519.pub:ro"
      - "~/.ssh/id_ed25519:/root/.ssh/id_ed25519:ro"

For more options, please refer to the Docker Compose docs.