​
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 and uses a default JWT authentication.

# create a jwt secret for auth
echo "JWT_SECRET_KEY=$(openssl rand -hex 32)" >> .env
# download and run
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.

Going with basic JWT Authentication is recommended because it’s the fastest way to get started.

The .env file must be at the same level as the docker-compose.yml file

This will generate a secret key for you and set it in the .env file already.

echo "JWT_SECRET_KEY=$(openssl rand -hex 32)" >> .env

Then, access the .env file and add the following configuration lines for your host configuration

.env
# the JWT_SECRET_KEY will be here already from the previous command
JWT_SECRET_KEY=<your-secret-key>

# 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:

​
Create your first connection

Now that you have access to the developer portal, let’s create your first connection. We have a demo PostgreSQL connection that you can use to test the setup. Follow this guide to create your PostgreSQL demo.

1

Start with a Demo set up

In the main page click on Quick start button inside the Start with a Demo Setup area.

2

Interact with the PostgreSQL

After you click on the Quick start button, you will see the PostgreSQL demo connection created and ready to use with a sample SQL query. You can click on 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.