BirdsiteLive/INSTALLATION.md

# Installation

## Prerequisites 

You will need a Twitter API key to make BirdsiteLIVE working. First create an **Standalone App** in the [Twitter developer portal](https://developer.twitter.com/en/portal/projects-and-apps) and retrieve the API Key and API Secret Key. 

Please make sure you are using a **Standalone App** API Key and not a **Project App** API Key (that will NOT work with BirdsiteLIVE), if you don't see the **Standalone App** section, you might need to [apply for Elevated Access](https://developer.twitter.com/en/portal/products/elevated) as described in the [API documentation](https://developer.twitter.com/en/support/twitter-api/developer-account).


## Server prerequisites

Your instance will need [docker](https://docs.docker.com/engine/install/) and [docker-compose](https://docs.docker.com/compose/install/) installed and working. 

## Setup

Download the [docker-compose file](https://github.com/NicolasConstant/BirdsiteLive/blob/master/docker-compose.yml): 

```
sudo curl -L https://raw.githubusercontent.com/NicolasConstant/BirdsiteLive/master/docker-compose.yml -o docker-compose.yml
```

Then edit file: 

```
sudo nano docker-compose.yml
```

### Attributes to change in the docker-compose file

#### Personal info

* `Instance:Domain` the domain name you'll be using, for example use `birdsite.live` for the URL `https://birdsite.live`
* `Instance:AdminEmail` the admin's email, will be displayed in the instance /.well-known/nodeinfo endpoint
* `Twitter:ConsumerKey` the Twitter API key
* `Twitter:ConsumerSecret` the Twitter API secret key

#### Database credentials

The database credentials must be changed the same way in the **server** and **db** section.

* database name:
  * `Db:Name`
  * `POSTGRES_DB`
* database user name:
  * `Db:User`
  * `POSTGRES_USER`
* database user password:
  * `Db:Password`
  * `POSTGRES_PASSWORD`

## Startup

Launch the app with:

```
docker-compose up -d
```

By default the app will be available on the port 5000

## Nginx 

On a Debian based distrib:

```
sudo apt update
sudo apt install nginx
```

Check nginx status: 

```
sudo systemctl status nginx
```

### Create nginx configuration

Create your nginx configuration

```
sudo nano /etc/nginx/sites-enabled/{your-domain-name.com}
```

And fill your service block as follow:

```
server {
    listen        80;
    server_name   {your-domain-name.com};
    location / {
        proxy_pass         http://localhost:5000;
        proxy_http_version 1.1;
        proxy_set_header   Upgrade $http_upgrade;
        proxy_set_header   Connection keep-alive;
        proxy_set_header   Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;
    }
}
```

Save and start/restart your Nginx service 

```
sudo service nginx start
# or restart it if its already started
sudo service nginx restart
```

### Secure your hosted application with SSL

After having a domain name pointing to your instance, install and setup certbot:

```
sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d {your-domain-name.com}
```

Make sure you're redirecting all traffic to https when asked.

Finally check that the auto-renewal will work as espected:

```
sudo certbot renew --dry-run
```

### Set the firewall 

Make sure you're securing your firewall correctly:

```
sudo apt install ufw #if not installed
sudo ufw app list
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status
```

You should now have an up and running BirdsiteLIVE instance!

## Updating 

Make sure your data belong outside the containers before migrating (set by default). 

To update your installation to the latest release:

```
# Edit `docker-compose.yml` to update the version, if you have one specified
# Pull new images
docker-compose pull
# Start a new container, automatically removes old one
docker-compose up -d
```

## Auto-Updating

To set auto-updates on your deployment, add to the `docker-compose.yml` file this section:

```diff
version: "3"

networks:
    birdsitelivenetwork:
        external: false

services:
    server:
        image: nicolasconstant/birdsitelive:latest
        [...]

    db:
        image: postgres:9.6
        [...]
        
+   watchtower:
+       image: containrrr/watchtower
+       restart: always
+       container_name: watchtower
+       environment:
+           - WATCHTOWER_CLEANUP=true
+       volumes:
+           - /var/run/docker.sock:/var/run/docker.sock
+       command: --interval 300
```

## IP Whitelisting

If you want to use the IP Whitelisting functionality (see related [variable](https://github.com/NicolasConstant/BirdsiteLive/blob/master/VARIABLES.md)) and you are using the nginx reverse proxy set as before, please add the following: 

```
sudo nano /etc/nginx/sites-enabled/{your-domain-name.com}
```

``` diff
server {
    listen        80;
    server_name   {your-domain-name.com};
    location / {
        proxy_pass         http://localhost:5000;
        proxy_http_version 1.1;
        proxy_set_header   Upgrade $http_upgrade;
        proxy_set_header   Connection keep-alive;
        proxy_set_header   Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;
+       proxy_set_header   X-Real-IP $remote_addr;
    }
}
```

And edit the docker-compose file as follow: 

```diff
version: "3"

networks:
    birdsitelivenetwork:
        external: false

services:
    server:
        image: nicolasconstant/birdsitelive:latest
        restart: always
        container_name: birdsitelive
        environment:
            - Instance:Domain=domain.name
            - Instance:AdminEmail=name@domain.ext
+           - Instance:IpWhiteListing=127.0.0.1;127.0.0.2
+           - Instance:EnableXRealIpHeader=true
            - Db:Type=postgres
            - Db:Host=db
            - Db:Name=birdsitelive
            - Db:User=birdsitelive
            - Db:Password=birdsitelive
            - Twitter:ConsumerKey=twitter.api.key
            - Twitter:ConsumerSecret=twitter.api.key
        networks:
            - birdsitelivenetwork
        ports:
            - "5000:80"
        depends_on:
            - db

    db:
        image: postgres:9.6
        [...]
```

## More options 

You can find more options available [here](https://github.com/NicolasConstant/BirdsiteLive/blob/master/VARIABLES.md)