fileglancer-hub

Scripts and configuration files for deploying Fileglancer in production at Janelia. This deploys the fileglancer FastAPI server behind Uvicorn, as well as an Nginx reverse proxy server.

Development Deployment

This assumes you have a working Pixi installation.

1. Clone this repository

git clone git@github.com:JaneliaSciComp/fileglancer-hub.git
cd fileglancer-hub

2. Start the Fileglancer server

pixi run start

Production Deployment

When working with a shared server, make sure to set your umask so that everything is writeable by the group:

umask 002

Fileglancer Installation

In production the servers need to run as root in order to allow for setuid priviledge.

1. Download and install Pixi into /usr/local/bin

curl -fsSL https://pixi.sh/install.sh | sh
sudo cp $HOME/.pixi/bin/pixi /usr/local/bin/

2. Create the working directories

sudo install -d -m 2775 -o $USER -g $(id -gn) /opt/deploy /opt/data
mkdir -p /opt/deploy/fileglancer-hub
mkdir -p /opt/data/fileglancer # optional, if you want to use a sqlite database

3. Clone the repository into /opt/deploy/fileglancer-hub

cd /opt/deploy/
git clone git@github.com:JaneliaSciComp/fileglancer-hub.git
cd fileglancer-hub

4. Create a file at /opt/deploy/fileglancer-hub/.env with the following content (modify the FGC_EXTERNAL_PROXY_URL to use the server hostname):

FGC_EXTERNAL_PROXY_URL=https://fileglancer-dev.int.janelia.org/files

FGC_DB_URL=sqlite:////opt/data/fileglancer/sqlite.db
# FGC_DB_URL=postgresql://<username>:<password>@<host>:<port>/<database>
FGC_DB_POOL_SIZE=5
FGC_DB_MAX_OVERFLOW=0

FGC_LOG_LEVEL=DEBUG

FGC_ATLASSIAN_URL=https://wikis.janelia.org
FGC_ATLASSIAN_USERNAME=<username here>
FGC_ATLASSIAN_TOKEN=<token here>

FGC_ENABLE_OKTA_AUTH=True // set to False to enable simple insecure auth for testing

FGC_OAUTH_CLIENT_ID=<client id from okta>
FGC_OAUTH_CLIENT_SECRET=<client secret from okta>
FGC_OAUTH_DOMAIN=<okta domain, e.g. hhmi.okta.com>
FGC_OAUTH_CALLBACK_DOMAIN=<the domain of the hub, e.g. fileglancer.int.janelia.org>

6. Install the systemd service files

sudo cp fileglancer.service /etc/systemd/system/fileglancer.service

7. Enable the services

sudo systemctl enable fileglancer

8. Start the service

sudo systemctl start fileglancer

NGINX Reverse Proxy Installation

1. Install nginx

sudo yum install nginx

2. Copy the nginx configuration file to /etc/nginx/conf.d/fileglancer.conf

sudo cp nginx.conf /etc/nginx/conf.d/fileglancer.conf

3. Set up the static path for the Fileglancer assets

find /opt/deploy/fileglancer-hub/ -name "assets"

Use this path to replace the <path_to_fileglancer_assets> placeholder in the Nginx configuration file (/etc/nginx/conf.d/fileglancer.conf).

find /opt/deploy/fileglancer-hub/ -name "ui"

Use this path to replace the <path_to_fileglancer_ui_directory> placeholder in the Nginx configuration file (/etc/nginx/conf.d/fileglancer.conf).

4. Build and serve Neuroglancer

Clone and build Neuroglancer from source (requires npm):

cd /opt/deploy
git clone https://github.com/google/neuroglancer.git
cd neuroglancer
npm install
npm run build

The build output lands in /opt/deploy/neuroglancer/dist/client. The /neuroglancer/ location block in nginx.conf serves this directory directly. If you built to a different path, update the alias in that block accordingly.

5. Disable the default server block

• comment out the default server block in the main Nginx configuration file

sudo nano /etc/nginx/nginx.conf

6. Obtain the SSL certificate for *.int.janelia.org and install it in /etc/nginx/certs/

sudo mkdir -p /etc/nginx/certs/
sudo cp cert.pem /etc/nginx/certs/default.crt
sudo cp key.pem /etc/nginx/certs/default.key

• Make sure the permissions are correct

sudo chown root:root /etc/nginx/certs/default.crt
sudo chown root:root /etc/nginx/certs/default.key
sudo chmod 644 /etc/nginx/certs/default.crt
sudo chmod 600 /etc/nginx/certs/default.key

7. Set up the per-job app-service HTTPS proxy

This lets a browser reach a running app service directly at https://job-<id>-<mac>.services.int.janelia.org/. The <mac> label is a signature over the job id, keyed by Fileglancer's session_secret_key, so the subdomains cannot be enumerated.

• Wildcard SSL certificate for *.services.int.janelia.org (or *.services-dev.int.janelia.org for dev). Install it as:

  sudo cp /path/to/services-cert.pem /etc/nginx/certs/services-wildcard.crt
  sudo cp /path/to/services-key.pem /etc/nginx/certs/services-wildcard.key
  sudo chown root:root /etc/nginx/certs/services-wildcard.crt /etc/nginx/certs/services-wildcard.key
  sudo chmod 644 /etc/nginx/certs/services-wildcard.crt
  sudo chmod 600 /etc/nginx/certs/services-wildcard.key

  If using Let's Encrypt, optionally symlink instead of copying so renewals stay live:

  sudo ln -sf /etc/letsencrypt/live/services.int.janelia.org/fullchain.pem /etc/nginx/certs/services-wildcard.crt
  sudo ln -sf /etc/letsencrypt/live/services.int.janelia.org/privkey.pem  /etc/nginx/certs/services-wildcard.key

• Resolver in nginx.conf — The resolver 127.0.0.53 valid=30s; line in the repo is a placeholder. Find the host's real nameservers, edit the line to match, then reload:

  cat /etc/resolv.conf   # nameserver lines
  sudo nano /etc/nginx/conf.d/fileglancer.conf   # update the resolver line
  sudo systemctl reload nginx

• FGC_APPS__SERVICE_PROXY_DOMAIN in .env — set to the same domain as the DNS record and certificate above (e.g. services.int.janelia.org, or services-dev.int.janelia.org for dev), then restart the fileglancer service.

• FGC_SESSION_SECRET_KEY in .env — required once the proxy domain is set; Fileglancer refuses to start without it, because the hostname labels are signed with it. Use a long random string (openssl rand -hex 32) and keep it stable: rotating it invalidates every live service URL along with every session.

To verify the certificate nginx is actually serving for a given job hostname (bypasses browser cache):

openssl s_client -connect job-<id>-<mac>.services.int.janelia.org:443 -servername job-<id>-<mac>.services.int.janelia.org </dev/null 2>/dev/null | openssl x509 -noout -subject

8. Enable the service

sudo systemctl enable nginx

9. Start the service

sudo systemctl start nginx

Administration

Updating to a new version

First, update to the version of Fileglancer you want to deploy:

cd /opt/deploy/fileglancer-hub
git pull

Then restart the services:

sudo systemctl restart fileglancer
sudo systemctl restart nginx

Make sure to check the logs and smoketest the service to ensure everything came up correctly.

Hub status checks

sudo systemctl status fileglancer
sudo systemctl status nginx

Check the logs of the services

sudo journalctl -o cat -fu fileglancer
sudo journalctl -fu nginx

Maintenance Mode

The nginx configuration includes maintenance mode functionality that will display a maintenance page when needed.

Enabling Maintenance Mode

1. Copy the example maintenance page to the nginx html directory:

sudo cp maintenance.html.example /etc/nginx/html/maintenance.html

2. If desired, edit the maintenance page to uncomment the estimated completion time section:

sudo nano /etc/nginx/html/maintenance.html

Replace [UPDATE WITH ACTUAL TIME] with the actual estimated completion time.

3. Reload nginx to activate maintenance mode:

sudo systemctl reload nginx

Disabling Maintenance Mode

1. Remove the maintenance page:

sudo rm /etc/nginx/html/maintenance.html

2. Reload nginx:

sudo systemctl reload nginx

Note: When maintenance mode is active, all requests to the main site and /fc/files/ endpoints will show the maintenance page instead of the normal application. Static assets like /fg/assets/ and /fg/logo.svg will continue to work normally to ensure the maintenance page displays correctly.