~cadence/bibliogram-docs

bibliogram-docs/docs/Installing (extended).md -rw-r--r-- 7.5 KiB
996a68a1 — Cadence Ember Remove totally dead instances 7 days ago

#Installing

If you haven't already, see docs/Installing (basic).md for more brief and more automated options.

Please add your own experiences and suggestions by submitting a patchset!

#Installing node.js

Bibliogram runs on node.js. If you don't have node.js, install it now. Versions before 12.13.0 have not been tested, so make sure you have at least 12.13.0 installed. Versions in the 13.x series and higher should be fine.

#Installing Bibliogram

Clone the repo:

$ git clone https://git.sr.ht/~cadence/bibliogram
$ cd bibliogram

Install dependencies: (choose one)

$ npm install --no-optional   # to install without outgoing Tor support; recommended!
$ npm install                 # to install with outgoing Tor support, 68 MB+ download required

#Configuring Bibliogram

You should do this before first launch. You must set website_origin to an appropriate value. All other options have acceptable defaults.

docs/Configuring.md →

#Running Bibliogram

$ npm run start

Bibliogram is now running on 0.0.0.0:10407. Access it by visiting http://localhost:10407.

#Making Bibliogram accessible from outside

At this point, Bibliogram is only accessible locally, on your computer/server, from http://localhost:10407. This section will explain how to make it accessible from outside. Otherwise, if you are satisfied in using it locally, you can stop reading.

#Port forwarding

If you're using a server that is inside your house behind a router, you will need to setup [[port forwarding]].

#Configuring DNS

At this point, you want to configure your domain name DNS to point to your Bibliogram server.

  1. Use an A record that points to the IP address of your server.
  2. If your server have a dynamic IP address (most likely if it's a home server), you need to use Dynamic DNS. Your domain name provider likely have documentation on how to setup that. If unsure, you can skip this step and do it later when your IP address changes.

The exact instructions on how to configure your DNS is outside of the score of this documentation. Your domain name provider will have documentation on how to do that.

To test that your DNS is configured properly, you can open your browser and type the URL you're planning to use along with Bibliogram's port number 10407 (for example http://bibliogram.example.com:10407). You should see Bibliogram running. At this point, if you don't care about HTTPS, or having the port number in your URL, you can stop reading.

#Configuring HTTPS

nginx is a reverse proxy that accepts connections from the outside world and forwards them to Bibliogram, all within your server. You can use it to provide HTTPS. You'll still have to get your own TLS certificates for nginx to use, so do that first.

Start by installing nginx from your package manager.

# apt install nginx

Then download dhparam.pem (Why?)

# mkdir -p /etc/nginx/ssl
# wget https://ssl-config.mozilla.org/ffdhe2048.txt -O /etc/nginx/ssl/dhparam.pem

Then create a file inside the directory /etc/nginx/sites-available (suggested name: bibliogram-proxy) with contents like this:

server {
    listen 80 default_server; # [6]
    listen [::]:80 default_server; # [6]
    server_name bibliogram.example.com; # [1]
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2 default_server; # [6]
    listen [::]:443 ssl http2 default_server; # [6]
    server_name bibliogram.example.com; # [1]
    ssl_certificate /etc/letsencrypt/live/bibliogram.example.com/fullchain.pem; # [3]
    ssl_certificate_key /etc/letsencrypt/live/bibliogram.example.com/privkey.pem; # [3]
    ssl_session_timeout 1d; # [2]
    ssl_session_cache shared:MozSSL:10m; # [2]
    ssl_session_tickets off; # [2]
    ssl_dhparam /etc/nginx/ssl/dhparam.pem; # [2] [5]
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384; # [2]
    ssl_prefer_server_ciphers off; # [2]
    client_max_body_size 5M;
    location / {
        proxy_set_header X-Forwarded-For $remote_addr; # [4]
        proxy_pass http://localhost:10407;
    }
}
  • [1] Write your actual domain here in place of bibliogram.example.com, in lower case. Do not use capital letters.
  • [2] Generated from the "intermediate" setting on https://ssl-config.mozilla.org (info) without HSTS or OCSP. Using the provided settings should be acceptable for most instances. If you want a more secure configuration, use that page on the "modern" setting, but check compatibility here first.
  • [3] Write your actual domain here in place of bibliogram.example.com. If your certificate is not from Let's Encrypt, you'll have to replace the entire path.
  • [4] Bibliogram can use this header to enforce quotas and stop abuse. You should not change this.
  • [5] More information.
  • [6] nginx allows a maximum of one default_server for each outgoing port. If you run other services on the same machine, and you want to make one of those the default_server, you should remove default_server from the Bibliogram configuration. More information.

Set the configuration as enabled:

# cd /etc/nginx/sites-enabled
# ln -sv ../sites-available/bibliogram-proxy .

And delete the default "it works" server that comes with nginx:

# rm default

Check your configuration. If there are errors, find them and fix them. This sample config should be good on its own.

# nginx -t

Once there are no errors in the configuration, start nginx:

# systemctl start nginx

Enable the nginx service to automatically start nginx after a machine reboot:

# systemctl enable nginx

If nginx is already running, you only have to reload the configuration:

# systemctl reload nginx

Now set up CAA for your DNS. You must set up DNS before you can do this. Why is CAA important?

  1. First, go to the SSLMate CAA record generator.
  2. Enter your domain name, then press "auto-generate policy".
  3. Scroll the list and make sure all boxes are unchecked except for the one that has your certificate authority.
  4. If it's all good, go down to the "publish your CAA policy" section and examine the first code block. You need to create a DNS record with this information on your domain.

Once you've set everything up, open your domain (ex: https://bibliogram.example.com) in your browser and check that:

  1. The Bibliogram home page appears
  2. You are connected over HTTPS

Now that that works, run the Qualys SSL Labs server test to make sure your configuration is secure. The test will take a few minutes to run.