Local storage Gaia Hub 502 Bad Gateway


Using docker and nginx for Gaia hub. Stuck with 502 Bad Gateway, anyone here to debug this with?
Certbot was successful, default nginx config works, problem appears when gaia/master/hub/nginx.conf.sample is used. Ports match with nginx.conf.sample and Gaia hub config.json, as well as the docker run command:
docker run -d --restart=always -v $HOME/hub/config.json:/src/hub/config.json -p 3000:3000 -e CONFIG_PATH=/src/hub/config.json quay.io/blockstack/gaia-hub:latest


It looks like your docker script is exposing port 3000, but the config file specifies a port of 400. That could be causing the nginx server to fail to connect to the gaia hub.


Tried with all the ports set to 3000 and to 4000, neither did change the result.


Well, you should find the error in /var/log/nginx/error.log or where you keep it.

Then you should also check netstat -nelp to see at what port you’re listening on.

You can connect to your running container:

docker exec -it "container-id" bash

Since you’re basically running your gaia at port 4000, but you were exposing it at 3000 on your host, you should make sure the nginx references 3000, and your docker should be 3000:4000 so that port 4000 on the inside matches 3000 on the outside.

Really cool setting up a Gaia hub. I want to do it too now I’ve had a look at it :stuck_out_tongue:


Just to make sure we’re on the same page here, here’s contents of my config files (important parts):

  "servername": "localhost",
  "port": 3000,
  "driver": "disk",
  "readURL": "http://localhost:3000/",


upstream gaia_hub {
  server localhost:4000;
server_name MYDOMAIN;
        location / {
                proxy_set_header X-Real-IP $remote_addr;
                proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
                proxy_set_header Host $http_host;
                proxy_redirect off;
                proxy_pass http://gaia_hub;

Here’s the command i ran for docker

docker run -d --restart=always -v $HOME/hub/config.json:/src/hub/config.json -p 3000:4000 -e CONFIG_PATH=/src/hub/config.json quay.io/blockstack/gaia-hub:latest

$HOME/hub has just one file config.json


Okay, so you have 3000 on the inside and 4000 on the outside then.

So you need to swap the -p params to be: -p 4000:3000. The first is the “host port” the last is the “container port” IIRC.

Also unsure whether servername: localhost would only bind to localhost in gaia. I actually don’t know Gaia yet, but I know docker and nginx, which is two out of three :slight_smile:


Switching the ports around did not solve it either.

About this I’m not sure, hopefully there’s someone here with more experience on this who can explain if this could be causing the problem.


Recall that Gaia hubs only handle POST requests. Your nginx proxy will need to serve your Gaia hub’s files back. This means that you’ll have two URLs: a write url (e.g. http://localhost:3000 according to your Gaia config file) and a read URL (e.g. http://my.gaia/hub or http://localhost:3001 or something)

In your Gaia config, you’re going to want your readURL to correspond to the publicly routable hostname and URL path prefix (i.e. the one that your nginx instance serves). If you stand up a nginx proxy in front of a Gaia hub, and that nginx proxy serves content for http://localhost:3001/hub, then the readURL in the Gaia config file should be http://localhost:3001/hub.

At the same time, in the nginx server block, you will want GET requests on paths that start with /hub to be served out of the directory on disk where your Gaia hub is writing its files. A GET /hub/foo should be handled by nginx by serving the file foo from the directory to which your Gaia hub is configured to write. Similarly, a POST /hub/foo should cause your Gaia hub to write the file foo to that directory.

In your Gaia config, servername and port correspond to the address the Gaia hub binds on. If you intend for your nginx proxy to proxy writes, then your upstream gaia_hub block in your nginx config should contain server localhost:3000; Moreover, your nginx proxy needs to serve files on 3001.


I think i have problem understanding the configuration file.
Now it seems that hub/config.sample.disk.json has been removed from Blockstack Github for some reason and there’s very little information on what info in that file represents.
With that getting deleted, where can i find a sample of configuration file that serves files locally?
Right now i can only see the cached code block on this forum of the delete github file:

  "servername": "localhost",
  "port": 4000,
   // what does this port serve? Is it pointing to the Docker instance and acting as a url for serving post
   // requests?
  "driver": "disk",
  "readURL": "http://localhost:4000/",
  "proofsConfig": {
    "proofsRequired" : 0
  "diskSettings": {
     "storageRootDirectory": "/tmp/gaia-disk"
  // is this still up to date? I can not see such entry in hub/config.sample.json
  "argsTransport": {
    "level": "debug",
    "handleExceptions": true,
    "stringify": true,
    "timestamp": true,
    "colorize": false,
    "json": true

Also does the directory $HOME/hub need any other files than the configuration such as files from github.com/blockstack/gaia/blob/master/hub/ or those are server via Docker?


Hey @Richy,

Looks like @aaron just released version 2.2 of Gaia :tada:. The config sample file you’re looking for got moved in the release to here.

In the config file you linked, please also note that you need to have a HTTP server serve files out of /tmp/gaia-disk in this case, since Gaia hubs only handle writes. You can use this program for that, since it will correctly serve files and handle CORS pre-flight checks and will honor your settings in your gaia.conf file automatically.


I’ve ran gaia-read.py along with correct config path and get the following error

Traceback (most recent call last):
  File "/root/hub/gaia-read.py", line 100, in <module>
    res = requests.get(gaia_write + '/hub_info')
  File "/usr/lib/python2.7/dist-packages/requests/api.py", line 70, in get
    return request('get', url, params=params, **kwargs)
  File "/usr/lib/python2.7/dist-packages/requests/api.py", line 56, in request
    return session.request(method=method, url=url, **kwargs)
  File "/usr/lib/python2.7/dist-packages/requests/sessions.py", line 488, in request
    resp = self.send(prep, **send_kwargs)
  File "/usr/lib/python2.7/dist-packages/requests/sessions.py", line 609, in send
    r = adapter.send(request, **kwargs)
  File "/usr/lib/python2.7/dist-packages/requests/adapters.py", line 487, in send
    raise ConnectionError(e, request=request)
requests.exceptions.ConnectionError: HTTPConnectionPool(host='localhost', port=4000): Max retries exceeded with url: /hub_info (Caused by NewConnectionError('<requests.packages.urllib3.connection.HTTPConnection object at 0xb5f855d0>: Failed to establish a new connection: [Errno 111] Connection refused',))

I’ve made sure that the storageRootDirectory exists and has folder gaia-disk.
Do i need to run the Docker instance here or that’s not needed anymore at all? Any open ports needed?


The problem is that your Gaia hub isn’t accessible on port 4000 for some reason. If you’re running this in Docker, you’ll need to expose that port (however, you shouldn’t need to run it in Docker–it’s just a node.js process that doesn’t need anything special).


Right now i simply downloaded just the gaia-read.py file into folder where my configuration file is.
Ran ./gaia-read.py ./config.json with no Docker running.
Am i missing some piece here, some files, open port, anything else?


As this is still an open case, looking for any suggestions on ideas how to get this running from anyone.


Hey @Richy,

What does your config.json specify for your port and servername? The gaia-read.py program issues a GET request to https://servername:port/hub_info (or http if servername is localhost,, or ::1) in order to get the read URL prefix. From there, it determines what host and port to listen in in order to handle reads. It looks like it’s failing that initial GET request. Can you be sure that your Gaia hub is listening on port 4000 and responds to something like curl http://localhost:4000/hub_info?


Yes, the problem seems to be that I’m getting no response from /hub_info and so far I’m not understanding why. What are the steps to debug this? I’ve listed out code samples above, that’s exactly what I’m running. Trying to figure this out over forum posts will take way longer than having a chat directly, can we do that instead?