This Wiki provides a comprehensive guide to using Mamba for managing Python environments and Docker containers in the Mistral Chatbot project. It includes step-by-step instructions tailored to the class project and practical solutions to common issues.

1. Installation
2. Configuration
3. Implementation
4. Usage
5. Troubleshooting

In Docker, a base image is a starting point for creating a new Docker image. For this project, we use the python:3.11-slim base image. It’s a lightweight version of Python 3.11, which minimizes the size of the Docker image and speeds up build and execution times. It contains only the essential parts needed to run Python applications.

Fig 1: Selected base image.

Before installing Mamba, we need to install some necessary system dependencies. These are the tools that will allow us to download Mambaforge and perform other tasks needed for the setup:

apt-get update
apt-get install -y wget bzip2 ca-certificates
rm -rf /var/lib/apt/lists/*

• apt-get update: Updates the list of available packages.
• apt-get install -y: Installs the packages (wget, bzip2, and ca-certificates).
• rm -rf /var/lib/apt/lists/*: Cleans up unnecessary files to keep the Docker image small.

Fig 2: Installing dependencies.

Mambaforge is a pre-built version of Miniforge that includes Mamba. Mamba is a faster, more efficient alternative to Conda for managing Python environments. This section of the Dockerfile detects the system architecture (whether the machine is x86_64 or aarch64) and installs the correct version of Mambaforge.

arch=$(uname -m)
if [ "$arch" = "x86_64" ]; then
    wget https://github.com/conda-forge/miniforge/releases/latest/download/Mambaforge-Linux-x86_64.sh -O miniforge.sh
else
    wget https://github.com/conda-forge/miniforge/releases/latest/download/Mambaforge-Linux-aarch64.sh -O miniforge.sh
fi
bash miniforge.sh -b -p /opt/conda
rm miniforge.sh

• arch=$(uname -m): Checks the system’s architecture.
• wget: Downloads the installation script for the correct Mambaforge version.
• bash miniforge.sh: Runs the installer.
• rm miniforge.sh: Cleans up after the installation to reduce the image size.

Fig 3: Installing Mambaforge.

1. Install Homebrew (if not already installed):

   • Open a terminal and run:

     /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
     

   • Follow the prompts to install Homebrew.

2. Install Mambaforge using Homebrew:

brew install --cask mambaforge

3. Verify Installation:

mamba --version

1. Install WSL (Windows Subsystem for Linux):

• Follow instructions here to enable WSL and set up a Linux distribution (Ubuntu is recommended).

2. Install Mambaforge via WSL:

• Open your WSL terminal and run:

  wget https://github.com/conda-forge/miniforge/releases/latest/download/Mambaforge-Linux-x86_64.sh -O mambaforge.sh
  bash mambaforge.sh -b -p $HOME/mambaforge
  

3. Verify Installation:

$HOME/mambaforge/bin/mamba --version

Note: Running Mamba on WSL enables you to set up Linux-like environments on your Windows system for better compatibility with the Docker-based development flow. `

Mamba’s environment management works seamlessly within Docker containers, allowing you to create isolated environments for each service within the Mistral Chatbot project. By using Mamba, you can ensure that dependencies are installed and managed efficiently, without affecting the host system or other containers.

When setting up a Docker container for the Mistral Chatbot project, use Mamba to:

• Manage Python versions and dependencies within the container
• Ensure reproducibility by using requirements.txt to manage Python libraries
• Avoid conflicts between the system environment and project dependencies

Environment variables are key to configuring how the system behaves. For Docker containers, these variables ensure that Python runs efficiently and that package management tools work seamlessly without requiring manual input.

export DEBIAN_FRONTEND=noninteractive
export PYTHONUNBUFFERED=1
export PYTHONDONTWRITEBYTECODE=1

Below is the effect of setting the environment variables that ensure smooth container operation.

• DEBIAN_FRONTEND=noninteractive: Prevents the package manager from asking for user input.
• PYTHONUNBUFFERED=1: Forces Python to output logs directly (no buffering), which is important for real-time logging in containers.
• PYTHONDONTWRITEBYTECODE=1: Prevents Python from generating .pyc files, saving space.

Fig 4: Set environment variables

Once Mambaforge is installed, we create a new isolated Python environment. This ensures that your project's dependencies won’t interfere with other projects or system-wide installations.

mamba create -n team2_env python=3.11 -y

• mamba create -n team2_env python=3.11 -y: Creates a Python 3.11 environment named team2_env.

Fig 5: Create a new environment with Python 3.10

To ensure the environment is easily accessible, the bin directory from the team3_env environment is added to the system’s PATH variable. This allows you to run commands like python or pip without needing to specify their full path.

Fig 6: Add Mambaforge to PATH

• Adds the Python executables from team2_env to the system’s PATH, making them available globally.

After the base environment is set up, the necessary Python environment is created with Mamba. This ensures that all dependencies are isolated within the team2_env environment.

Fig 7: Activate the environment

1. Prepare requirements.txt: Ensure that requirements.txt contains all necessary dependencies for the Mistral Chatbot project.

2. Copy requirements.txt into the Docker Image:

COPY requirements.txt /app/requirements.txt

3. Install Dependencies with Mamba:

RUN mamba install --yes --file /app/requirements.txt

4. Clean Up Cache: To keep the Docker image size small, remove unnecessary caches:

RUN mamba clean --all -f -y

This process ensures that all dependencies for your project are installed efficiently and the Docker image remains lean.

• COPY requirements.txt /app/requirements.txt: Copies the requirements.txt file into the Docker image.
• RUN mamba install --yes --file requirements.txt: Installs the dependencies listed in requirements.txt.
• mamba clean --all -f -y: Cleans up package caches to reduce the Docker image size.

Fig 8: Install Python packages from requirements.txt

1. Create Dockerfile: Ensure your Dockerfile is set up as shown in the "Installation" section.

2. Run Docker Build Command: In the terminal, navigate to the project directory (where the Dockerfile is located) and run the following command:

docker build -t team2_app .

3. Verify Docker Image: After building the image, confirm that the Docker image is successfully created:

docker images

4. Inspect Build Logs: You can check the progress of the build with:

docker build -t team2_app . --progress=plain

This will provide detailed logs of each build step.

Fig 9: Build execution

This command reads the instructions from the Dockerfile and creates an image named team2-app. Building the Docker image involves several steps:

• Downloading the Base Image: The image starts with the python:3.10-slim base image.
• Installing System Dependencies: Necessary system dependencies like wget, bzip2, and python3-dev are installed.
• Installing Mambaforge: Mambaforge is downloaded and installed based on the architecture (x86_64 or aarch64).
• Setting up Python Environment: A Python 3.10 environment (team2_env) is created using Mamba.
• Installing Python Packages: Dependencies from requirements.txt are installed, followed by additional Python packages via pip.

After the image is built, you’ll have a fully contained, ready-to-run version of your application that can be deployed anywhere Docker is supported.

• Portability: Docker images encapsulate all the software, libraries, and dependencies needed to run your application. This ensures your container can run on different systems or cloud environments without compatibility issues.

• Consistency: Docker ensures the environment your application runs in is identical from development to production. This eliminates the "it works on my machine" problem, as the container guarantees a consistent runtime environment.

• Scalability: Docker simplifies scaling applications by allowing you to run multiple instances of the same container across various servers or cloud nodes.

By containerizing your application, you make deployment, scaling, and maintenance more efficient, especially in complex production environments.

Once the image is built, run the container with the following command:

docker run -d -p 5002:5002 team2_app

If the Docker container is not functioning as expected, you can view the container logs to troubleshoot the issue. Use the following command to inspect logs:

1. Find the container ID:

docker ps

2. View the logs:

docker logs <container_id>

This command will show the output of the running container and can help identify errors or misconfigurations.

Fig 10: Docker execution

• docker run -d: Runs the container in the background (detached mode).
• --p 5002:5002: Maps port 5002 on the host to port 5002 inside the container, which is essential for web applications.
• team2-app: The name of the Docker image.

After running the command, the container will start, and your application will be accessible at: http://localhost:5002

Once the Mamba environment is set up for the Mistral Chatbot project, you can use Jupyter notebooks to interactively test and debug your project’s code. Ensure that Jupyter is installed within the team2_env environment, so you can access all your project dependencies directly within your notebooks.

To install Jupyter in the Mamba environment:

mamba install jupyter

To launch Jupyter:

jupyter notebook

This will open a Jupyter interface in your browser where you can run cells that test different features of the Mistral Chatbot, visualize data, and interact with your project’s code.

The ZAP (OWASP Zed Attack Proxy) tool can be integrated into the Mamba environment for security scanning of your Mistral Chatbot. To use ZAP:

1. Install ZAP in your environment:

mamba install zaproxy

2. Run the ZAP tool to scan for vulnerabilities in your web application:

zaproxy -daemon

3. Configure the ZAP tool to automatically detect security flaws and test endpoints of the chatbot application running in your Docker container.

To ensure that the application is accessible from outside the container, the Dockerfile includes an EXPOSE instruction:

This instruction makes port 5002 available for external connections. While EXPOSE doesn't automatically map the port to the host, it documents which port the application runs on and enables you to bind this port to the host when running the container.

In this case, port 5002 is used for the Streamlit application.

For more detailed steps on how to build the Docker image, see the Installation section.

If the system's architecture is not supported (neither x86_64 nor aarch64), the Docker build will exit with an error. To resolve this:

• Check your system architecture with uname -m.
• If unsupported, you may need to modify the Dockerfile to support your architecture or use a different toolchain.

• Error: Version mismatch during installation.

• Inspect requirements.txt for conflicting versions.

• Use mamba search <package_name> to check available versions and adjust as needed.

Sometimes, a package may fail to install due to unavailability in the Mamba repository. In this case:

• Search for the package in the Mamba repository.
• If unavailable, look for alternatives or adjust the requirements.txt.

If the Streamlit app doesn’t start, verify:

• The correct port is exposed in both the Dockerfile and the docker run command.
• Streamlit’s configuration is set to use the exposed port.
• Use docker logs <container_id> to inspect logs for potential issues.

Problem: There are compatibility issues between Mamba-installed packages and system dependencies.

Solution:

• Use the following command to install specific versions of packages to resolve conflicts:

mamba create -n <env_name> <package=version>

• You can check the compatibility of the installed versions by running:

mamba info

• Problem: Application not accessible at expected URL.
• Solution: Verify port mapping in the Docker run command and check docker logs.

• Problem: Errors when switching environments.
• Solution: Clear caches with mamba clean --all and restart Mamba. For persistent issues, try mamba env remove -n <env_name> before re-creating.

Problem: Permissions issues during installation on macOS or Linux.

Solution:

• On macOS/Linux, some installations may require elevated privileges. Use sudo to ensure successful installation:

sudo mamba install <package_name>

• On macOS, ensure that your security settings allow Mamba to run:

sudo spctl --master-disable

Note: These steps may vary depending on system-specific security settings.

Mamba’s environment setup can vary slightly depending on your operating system and the Python version you’re using. Here are some common variations:

If you encounter issues related to macOS permissions during installation, you might need to run the following commands with elevated privileges:

sudo mamba create -n team2_env python=3.11

You may also need to adjust the system’s security settings to allow Mamba to install packages.

On Windows, you can use the WSL (Windows Subsystem for Linux) to set up Mamba. Ensure that you have WSL installed, and then follow the standard Linux installation steps for Mambaforge.

bash miniforge.sh -b -p /opt/conda

Ensure that WSL is configured to run Ubuntu for best compatibility.

If you need a different version of Python (e.g., Python 3.10), adjust the environment creation command accordingly:

mamba create -n team2_env python=3.10 -y

This ensures compatibility with specific project dependencies that require older Python versions.

For more troubleshooting tips, visit the Mamba documentation.