> ## Documentation Index
> Fetch the complete documentation index at: https://hoopdev-fix-add-missing-mechanic-for-session-download-button.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Docker

> This deployment leverages `docker compose` to deploy Hoop on local or remote machines for solution assessment.

## Supported Operational Systems

<CardGroup cols={2}>
  <Card title="Linux" icon="linux">
    Tested on MacOS, Ubuntu 24.04 and Amazon Linux 2
  </Card>

  <Card title="MacOS" icon="apple">
    Intel based and Apple Silicon (M1/M2) Macs
  </Card>
</CardGroup>

## Required tooling

<Steps titleSize="h3">
  <Step title="Docker">
    Install or update to Docker version 20.10.0 or greater

    <CardGroup cols={2}>
      <Card title="Install Docker for Linux" icon="linux" iconType="brands" href="https://docs.docker.com/engine/install/ubuntu/#install-using-the-convenience-script" />

      <Card title="Install Docker for MacOS" iconType="brands" icon="apple" href="https://docs.docker.com/desktop/install/mac-install/" />
    </CardGroup>
  </Step>

  <Step title="Docker Compose">
    Install or update Docker Compose to version 2.11.x or greater
    <Info>Run `docker compose version` to check which version you have installed</Info>

    <CardGroup cols={2}>
      <Card title="Install Docker Compose for Linux" icon="linux" iconType="brands" href="https://docs.docker.com/desktop/install/linux-install/">
        It comes installed with Docker engine, but you can also do the standalone installation
      </Card>

      <Card title="Docker Compose for MacOS" iconType="brands" icon="apple">
        No need to install, it comes with Docker Desktop for MacOS
      </Card>
    </CardGroup>
  </Step>
</Steps>

## Download & Run in your machine

This simpler version doesn't require much configuration, it just runs in your localhost.

```sh theme={null}
touch .env && curl -sL https://hoop.dev/docker-compose.yml > docker-compose.yml && \
  docker compose up
```

This will download the docker-compose file and run it in your local machine. You can access it at `http://localhost:8009` in your browser.

If you want to set up a custom Identity Provider or run it in a remote machine, follow the **Download & Run in a remote machine** guide below.

## Download & Run in a remote machine

<Steps>
  <Step title="Download the Docker Compose file">
    ```sh theme={null}
    curl -sL https://hoop.dev/docker-compose.yml > docker-compose.yml
    ```
  </Step>

  <Step title="Set the .env file">
    This step is required for authentication mostly, but a lot more configurations can be added to your `.env` file.
    Check all the available configurations in the [environment variables section](/setup/configuration/env-vars).

    <Note>
      The `.env` file must be at the same level as the docker-compose.yml file
    </Note>

    <Tabs>
      <Tab title="Local Provider">
        The local provider is the default, it allows accessing the developer portal with password based authentication.

        * Create an `.env` file to add the following configuration lines for your host configuration

        ```sh .env theme={null}
        # the API_URL and GRPC_URL are the host where
        # the Hoop API and GRPC services are running
        API_URL=http://<your-vm-ip-or-host>:8009
        GRPC_URL=http://<your-vm-ip-or-host>:8010
        ```
      </Tab>

      <Tab title="Custom Identity Provider">
        Using a custom identity is now handled directly in the Webapp in the **Integrations** > **Authentication** page.
      </Tab>
    </Tabs>

    <Info>
      If you can't access the developer portal from a VM, check your firewall rules and make sure the port TCP/8009 and TCP/8010 are open or to bind properly the ports inside your network so it can be accessible.
    </Info>
  </Step>

  <Step title="Run">
    This process might take a few minutes to download the images and start the containers.

    ```sh theme={null}
    docker compose up
    ```
  </Step>

  <Step title="Manage the containers">
    To view the container logs:

    ```sh theme={null}
    docker compose logs -f
    ```

    To stop the containers:

    ```sh theme={null}
    docker compose down
    ```
  </Step>

  <Step title="Access the developer portal">
    If you are running this on your local machine, access `http://localhost:8009` in your browser.
    Or, if you are running this on a remote machine, access `http://<vm-public-dns>:8009` in your browser.

    <Info>
      If you can't access the developer portal from a VM, check your firewall rules and make sure the port TCP/8009 and TCP/8010 are open or to bind properly the ports inside your network so it can be accessible.
    </Info>
  </Step>
</Steps>

## Accessing and Getting Started with hoop.dev

Once you finish the setup, create an account and sign in to the developer portal, you will see this screen:

<Frame>
  <img src="https://mintcdn.com/hoopdev-fix-add-missing-mechanic-for-session-download-button/JA0PdC0o4BPvOEZ9/images/docker/home-screen.png?fit=max&auto=format&n=JA0PdC0o4BPvOEZ9&q=85&s=6fd5fbc2cee8449a1cb26721a7c9d981" width="3348" height="1806" data-path="images/docker/home-screen.png" />
</Frame>

Click to **explore with a demo database** and you will be able to create your first connection and start exploring the platform.

### Running Your First Query

Click in the **Run** button to execute the query and see the results.

<Frame>
  <img src="https://mintcdn.com/hoopdev-fix-add-missing-mechanic-for-session-download-button/JA0PdC0o4BPvOEZ9/images/docker/home-screen-postgres-demo-created.png?fit=max&auto=format&n=JA0PdC0o4BPvOEZ9&q=85&s=13233bdf73ab65ae76146f23b21455cf" width="3156" height="1614" data-path="images/docker/home-screen-postgres-demo-created.png" />
</Frame>

***

You have successfully set up Hoop on your local machine or remote server using Docker Compose. Now you can start exploring the platform and connecting to your data sources.

## Troubleshooting

### Production Environments with API\_URL

When deploying Hoop using Docker Compose for Production Environments, it's usually important to configure the `API_URL` environment variable properly to ensure the web app assets are served correctly. Check the following steps to configure it:

<Steps>
  <Step title="Set the full domain:">
    In your `.env` file, the `API_URL` should include the complete schema (e.g., `https://yourdomain.com`). This will ensure that assets are served with the correct schema and domain.
  </Step>

  <Step title="Updating your .env file:">
    Open your `.env` file and add the following:

    ```sh theme={null}
    API_URL=https://yourdomain.com
    ```

    Replace `https://yourdomain.com` with the full schema and host where you will serve the Hoop Gateway. If you encounter any issues after setting the `API_URL`, double-check your `.env` file and provide details about your setup for troubleshooting.

    <Info>
      If the `API_URL` variable is not set manually, it will default to `127.0.0.1`, which serves locally inside your virtual machine. To avoid this and serve the web app properly over the correct domain, ensure you update the `.env` file with your intended domain.
    </Info>
  </Step>

  <Step title="Handling IP and DNS forwarding:">
    If you configure the `API_URL` with an IP address and later use DNS port forwarding, the assets might not load correctly. The `API_URL` should reflect the full domain, not just the IP.
  </Step>
</Steps>