Troubleshooting

If you’re running Briefer in another machine, for example an external server, Raspbery Pi, etc - make sure you have enabled HTTPS for your current setup while accessing Briefer on port 3000.

In case you can’t enable HTTPS or just want to try it out over HTTP, you can run Briefer over HTTP by setting the ALLOW_HTTP environment variable to true:

ALLOW_HTTP=true briefer

Note that using ALLOW_HTTP will not set the session cookie as Secure, thus allowing you to sign in using HTTP. We don’t recommend using this option production.

Furthermore, if you’re using an older version of Briefer, you might need to delete older volumes which might contain conflicting data. You can do that by running:

# If you have data on disk (like files), you may want to back those files up before running these commands
# Still, these commands do *not* delete the data in your database (notebooks, dashboards, users, etc)
docker volume rm briefer_jupyter_data
docker volume rm briefer_briefer_data

If you’re not able to access the web application, Briefer is either not running or not exposed to the internet (or within your local network). The latter is the most common issue.

To check if Briefer is running, SSH into your server and run docker ps. You should see a container using the image briefercloud/briefer or briefercloud/briefer-web. If you don’t see it, Briefer is not running.

If Briefer is running, have a look at its logs and see if there are any errors. You can do that by running docker logs <container_id>, where <container_id> is the ID of the Briefer container.

Finally, make sure that you’ve exposed your server to the internet or your local network. You can do that by allowing traffic on port 3000 and creating the necessary DNS records to access the host. Finally, please ensure that the container’s port is bound to the host’s port (3000).

This problem is likely due to an issue with the WebSocket connection that Briefer uses to send code execution requests to the backend (and document edits).

If you’re using a reverse proxy, make sure that it’s configured to allow WebSocket connections. You can do that by adding the following configuration to your Nginx reverse proxy:

# WebSocket settings
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "Upgrade";

# Disable buffering for WebSocket
proxy_buffering off;
proxy_cache_bypass $http_upgrade;

# Timeouts for long-polling
proxy_read_timeout 60s;
proxy_send_timeout 60s;

If you’re using a different reverse proxy, make sure to check its documentation for WebSocket configuration.

In this case, it’s likely that the web process is running, but the API is not.

If the API is running, have a look at its logs and see if there are any errors. You can do that by running docker logs <container_id>, where <container_id> is the ID of the API container or the monolithic Briefer container in case that’s what you’re using.

Check if it complains about any missing environment variables or if there’s any other straightforward error that you can solve.

If you can’t figure out what’s happening, please open an issue here.

This is likely an issue with encrypting and decrypting tokens. It usually happens when you have lingering data from a previous execution while having changed Briefer’s encryption keys.

To fix this issue, start by clearing your browser’s cookies and local storage. Then, try accessing Briefer again.

If you still can’t access Briefer you may have to remove Briefer’s old docker volumes.

docker volume rm briefer_jupyter_data
docker volume rm briefer_briefer_data

Briefer accepts the following environment variables to configure the SSL connection to your Postgres instance:

• POSTGRES_SSL_DISABLED: Set this to true to disable SSL.
• POSTGRES_SSL_REJECT_UNAUTHORIZED (optional): Set this to true to reject unauthorized (self-signed) SSL certificates.
• POSTGRES_SSL_CA: (optional): The path to the CA certificate file to validate the server certificate.

If you’re having issues with your Postgres SSL settings, make sure that you’ve set these environment variables correctly.

By default, Briefer’s connection will have the same SSL settings as using sslmode=prefer in a Postgres connection string.