Docker
==========

.. note::

    If you are running on a non-bare metal server, or prefer not to use VMware and VirtualBox platforms, Docker is the recommended option. For optimal performance, KVM support is recommended.

Prerequisite Check
-----------------

Before installing Docker, check if your machine supports KVM (recommended for better performance):

On Linux, run:

.. code-block:: bash

    egrep -c '(vmx|svm)' /proc/cpuinfo

If the return value is greater than zero, your processor supports KVM.

.. note::

    macOS hosts generally do not support KVM. For macOS users, we recommend using VMware instead.

Docker Installation
------------------

Choose the appropriate installation method based on your system:

1. **For systems with GUI**:
   
   - For Linux: Follow the `Docker Desktop for Linux <https://docs.docker.com/desktop/install/linux-install/>`_ installation guide
   - For Windows: Follow the `Docker Desktop for Windows <https://docs.docker.com/desktop/install/windows-install/>`_ installation guide

2. **For systems without GUI**:
   
   Follow the `Docker Engine installation guide <https://docs.docker.com/engine/install/>`_

Verification
-----------

Verify the installation by running:

.. code-block:: bash

    docker --version


Usage Example
------------

To use Docker as your provider, initialize the DesktopEnv with the following parameters:

.. code-block:: python

    # Initialize environment with Docker provider
    env = DesktopEnv(
        provider_name="docker",
        os_type="Ubuntu"  # or "Windows" if you want to create a Windows VM
    )


Customizing the VM Image
------------------------

If you want to customize the client machine image (e.g., adding additional tools, software, or configurations), you can modify the VM image directly using Docker:

1. **Start the VM with persistent storage**:

   .. code-block:: bash

       docker run -it --rm \
         -e "DISK_SIZE=64G" \
         -e "RAM_SIZE=8G" \
         -e "CPU_CORES=8" \
         --volume "$(pwd)/docker_vm_data/Ubuntu.qcow2:/boot.qcow2" \
         --cap-add NET_ADMIN \
         --device /dev/kvm \
         -p 8006:8006 \
         -p 5000:5000 \
         happysixd/osworld-docker

2. **Access the VM**: 
   Connect to the VNC interface at `http://localhost:8006` to access the VM desktop.

3. **Make your customizations**:
   - Install additional software packages
   - Configure applications
   - Add custom tools or scripts
   - Modify system settings

4. **Save changes**: 
   Properly shut down the VM from within the guest OS. All changes will be automatically persisted to the `Ubuntu.qcow2` file.

.. note::
   
   Make sure the VM is properly shut down (not force-stopped) to ensure all changes are saved to the disk image.


Clean-up Note
------------

.. important::

    If experiments are interrupted abnormally, there may be residual docker containers. To clean up, run:

    .. code-block:: bash

        docker stop $(docker ps -q) && docker rm $(docker ps -a -q)