​
Supported Operational Systems

Linux

Tested on MacOS, Ubuntu 24.04 and Amazon Linux 2

MacOS

Intel based and Apple Silicon (M1/M2) Macs

​
Required tooling

1

Docker

Install or update to Docker version 20.10.0 or greater

Install Docker for Linux

Install Docker for MacOS

2

Docker Compose

Install or update Docker Compose to version 2.11.x or greater
Run docker compose version to check which version you have installed

Install Docker Compose for Linux

It comes installed with Docker engine, but you can also do the standalone installation

Docker Compose for MacOS

No need to install, it comes with Docker Desktop for MacOS

​
Download & Run in your machine

This simpler version doesn’t require much configuration, it just runs in your localhost. 
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

1

Download the Docker Compose file

curl -sL https://hoop.dev/docker-compose.yml > docker-compose.yml
2

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.
The .env file must be at the same level as the docker-compose.yml file
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
.env
# 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
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.
3

Run

This process might take a few minutes to download the images and start the containers.
docker compose up
4

Manage the containers

To view the container logs:
docker compose logs -f
To stop the containers:
docker compose down
5

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.
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.

​
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:
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.
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:
1

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.
2

Updating your .env file:

Open your .env file and add the following:
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.
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.
3

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.