# Docker Compose
Codebox supports docker-compose standard to define the structure of a workspace.

## Compose file
While you can use a regular Docker Compose configuration to define your workspace, Codebox provides a set of custom labels that can be added to containers to seamlessly integrate your stack with the Codebox environment.

The docker-compose file can be loaded from either a Git repository or a predefined template.

## Labels

### Expose a port
You can configure the default exposed ports for services using labels:
- Use the label `com.codebox.port.<service_name>` to bind a service to a specific port (e.g., `com.codebox.port.phpmyadmin=80`).
- Use the label `com.codebox.port.<service_name>.public` to define the port's visibility (e.g., `com.codebox.port.phpmyadmin.public=false`). By default, ports are not publicly accessible (`false`).

### Workspace path
You can specify the working directory path using the `com.codebox.workspace_path` label. This path will be used as the default location opened by IDE integrations and remote connections (e.g., `com.codebox.workspace_path=/workspace`).

### Container user
You can specify the default user for container access using the `com.codebox.user` label. If not set, Codebox will attempt to automatically determine the appropriate username (e.g., `com.codebox.user=user`).

## Environment
Codebox provides a set of default environment variables that can be used within your Docker Compose configuration. All of these variables — except for the email address — are automatically converted to lowercase before being injected. You can also define your own custom environment variables as needed. The default environment variables include:
- `CODEBOX_WORKSPACE_ID` – The unique identifier of the workspace
- `CODEBOX_WORKSPACE_NAME` – The name of the workspace
- `CODEBOX_WORKSPACE_OWNER_EMAIL` – The email address of the workspace owner
- `CODEBOX_WORKSPACE_OWNER_FIRST_NAME` – The first name of the workspace owner
- `CODEBOX_WORKSPACE_OWNER_LAST_NAME` – The last name of the workspace owner
- `CODEBOX_WORKSPACE_RUNNER_ID` – The ID of the runner managing the workspace
- `CODEBOX_WORKSPACE_RUNNER_NAME` – The name of the runner managing the workspace

### Example
```yml
version: "3.8"

services:
    dev:
        build:
            context: .
            args:
                USER_NAME: ${CODEBOX_WORKSPACE_OWNER_FIRST_NAME:-}
                USER_EMAIL: ${CODEBOX_WORKSPACE_OWNER_EMAIL:-}
                USER_FIRST_NAME: ${CODEBOX_WORKSPACE_OWNER_FIRST_NAME:-}
                USER_LAST_NAME: ${CODEBOX_WORKSPACE_OWNER_LAST_NAME:-}
        stdin_open: true
        tty: true
        volumes:
            - /var/run/docker.sock:/var/run/docker.sock
            - workspace:/home/${CODEBOX_WORKSPACE_OWNER_FIRST_NAME:-}
        labels:
            - com.codebox.user=${CODEBOX_WORKSPACE_OWNER_FIRST_NAME:-}

volumes:
    workspace:
```
You can view the full source code and more examples [here](https://gitlab.com/codebox4073715/codebox/-/tree/master/examples/docker-compose).

## Volumes

Docker volumes can be used to store persistent data link in a normal docker stack.

### Warning

You should only use host folder binding to access host resources like docker sock, use docker volumes to store data.