# Installing

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

[basic]: https://git.sr.ht/~cadence/bibliogram-docs/tree/master/docs/Installing%20%28basic%29.md

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.](https://nodejs.org/en/) 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 GraphicsMagick

GraphicsMagick is required for resizing images for thumbnailing.

It's almost certainly available in your package manager.

Ubuntu/Debian: `apt install graphicsmagick`

## 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` →][configuring]

[configuring]: https://git.sr.ht/~cadence/bibliogram-docs/tree/master/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.
1. 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.](https://letsencrypt.org)

Start by installing nginx from your package manager.

    # apt install nginx

Then download `dhparam.pem` ([Why?][why dhparam])

    # 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][mozilla sec 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.][caniuse 1.3]
- `[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.][why dhparam]
- `[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.][default server info]

[mozilla sec info]: https://wiki.mozilla.org/Security/Server_Side_TLS
[caniuse 1.3]: https://caniuse.com/#feat=tls1-3
[why dhparam]: https://security.stackexchange.com/questions/94390/whats-the-purpose-of-dh-parameters/94397#94397
[default server info]: https://nginx.org/en/docs/http/request_processing.html

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?][why caa]

[why caa]: https://blog.qualys.com/ssllabs/2017/03/13/caa-mandated-by-cabrowser-forum

1. First, go to the [SSLMate CAA record generator.][caa generator]
1. Enter your domain name, then press "auto-generate policy".
1. Scroll the list and make sure all boxes are unchecked _except_ for
the one that has your certificate authority.
1. 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.

[caa generator]: https://sslmate.com/caa/

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
1. You are connected over HTTPS

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

[ssl server test]: https://www.ssllabs.com/ssltest/