Skip to content

02-05-linkding-installation.md

Latest commit

 

History

History
239 lines (151 loc) · 14.4 KB

02-05-linkding-installation.md

File metadata and controls

239 lines (151 loc) · 14.4 KB

Server setup guide

Introduction

This file contains the linkding section of my personal guide to setup an Ubuntu server. The introduction to this guide as well as its full Table of Contents can be found on the README.md file of this repository. The Table of Contents of this section is listed below.

  1. Software Installation

    1. linkding installation
      1. Install linkding
      2. Reverse Proxy Setup
      3. Create and set an SSL Certificate
      4. www to non-www redirection

2.5. linkding installation

2.5.1. Install linkding

linkding will be installed using Docker. To prepare the folders necessary for the linkding installation, execute the following commands:

sudo mkdir /opt/linkding
sudo mkdir /opt/linkding/data
sudo mkdir /opt/linkding/docker-files

The folder /opt/linkding/docker-fileswill contain the files necessary to deploy linkding with Docker. To set better permissions for this folder, replace the {LABEL} in the below command as appropriate and execute it.

  sudo chown -R {USERNAME}:{USERNAME} /opt/linkding/docker-files/

Label Definition

  • {USERNAME} : The user that will deploy linkding

We will create a user to manage the linkding app deployed with Docker and set it as the owner of the folder /opt/linkding/data/. To create this user and set it as the owner of the folder /opt/linkding/data/, execute the following commands:

sudo useradd -r -s /usr/sbin/nologin linkding
sudo chown -R linkding:linkding /opt/linkding/data/

To download the customized docker-compose.yml and .env files from this repository to the server, execute the following commands:

cd /opt/linkding/docker-files/
wget https://raw.githubusercontent.com/EnduranceCode/server-setup-guide/refs/heads/master/system/opt/linkding/docker-files/docker-compose.yml
wget https://raw.githubusercontent.com/EnduranceCode/server-setup-guide/refs/heads/master/system/opt/linkding/docker-files/.env

To confirm that the files were downloaded, check the output of the following command:

ls -lag

Open the files docker-compose.yml and .env with the nano text editor and check if there are any changes needed. If you've made any modification, save it with the command CTRL + O and then close the editor with the command CTRL + X.

To complete the deployment of linkding, execute the following command:

docker compose -p linkding up -d

The output of the above command should show that linkding was deployed with success. For a second confirmation, check the output of the following command:

docker ps

The above command should show that the linkding container is being executed.

The linkding Docker image does not provide an initial user, so you have to create one after setting up the installation. To do so, replace the {LABEL} in the below command as appropriate and execute it.

  docker exec -it linkding python manage.py createsuperuser --username={USERNAME} --email={EMAIL}

Label Definition

  • {USERNAME} : The linkding administrator's username
  • {EMAIL} : The linkding administrator's e-mail

To check if linkding is running correctly, replace the {LABEL} in the below URL as appropriate and enter it into a browser’s address bar.

  http://{SERVER_IP_ADDRESS}:{LD_HOST_PORT}/

Label Definition

  • {SERVER_IP_ADDRESS} : The IP Address of the server that can be obtained with the command hostname -I or the command curl -4 icanhazip.com
  • {LD_HOST_PORT} : The port on the host system that the application was published on

2.5.2. Reverse Proxy Setup

To ensure that the necessary Apache Server modules for reverse proxying are enabled, execute the following commands:

sudo a2enmod proxy
sudo a2enmod proxy_http
sudo a2enmod headers
sudo systemctl reload apache2

Since linkding version 1.15, the application includes a CSRF check that verifies that the Origin request header matches the Host header. If the Host header is modified by the reverse proxy then this check fails with 403 CSRF verfication failed error. To fix this, you need to configure the LD_CSRF_TRUSTED_ORIGINS option to the URL from which you are accessing your linkding instance.

Open the.env file with the nano text editor, replace the {LABEL} in the below snippet as appropriate, and set it as the value of the LD_CSRF_TRUSTED_ORIGINS variable.

  http://{REQUEST_DOMAIN}.{REQUEST_TLD},https://{REQUEST_DOMAIN}.{REQUEST_TLD}

Label Definition

  • {REQUEST_DOMAIN} : The domain (and subdomain if applicable) of the request origin
  • {REQUEST_TLD} : The TLD of the request origin

After making all the necessary changes, save the file with the command CTRL + O and then close the editor with the command CTRL + X.

To load the new configuration, restart the linkding executing the following commands:

cd /opt/linkding/docker-files
docker compose restart

The output of the above command should show that linkding was restarted with success. For a second confirmation, check the output of the following command:

docker ps

The above command should show that the linkding container is being executed.

To check if linkding is running correctly, replace the {LABEL} in the below URL as appropriate and enter it into a browser’s address bar.

  http://{SERVER_IP_ADDRESS}:{LD_HOST_PORT}/

Label Definition

  • {SERVER_IP_ADDRESS} : The IP Address of the server that can be obtained with the command hostname -I or the command curl -4 icanhazip.com
  • {LD_HOST_PORT} : The port on the host system that the application was published on

To have a domain (or a subdomain) pointing to your linkding instance, you need to start by creating the DNS records of the desired domain (or subdomain) redirecting to your server's IP address.

After creating the necessary DNS Records, create an Apache Virtual Host for that domain (or a subdomain) following the instructions available in this repository. To download the template for the Virtual Host configuration file, execute the following command:

sudo wget -P /etc/apache2/sites-available/ https://raw.githubusercontent.com/EnduranceCode/system-configuration-files/refs/heads/master/root/etc/apache2/sites-available/virtual-host-template.conf

When customizing the Virtual Host configuration file downloaded with the previous command, besides replacing the {LABELS} listed on the provided instructions, replace also the label {APP_PORT} with the value set on the .env file for the HOST_PORT variable.

Check if it's necessary any further modifications, implement it if necessary and when everything is done, save the file with the command CTRL + O and then exit the nano text editor with the command CTRL + X. Then, proceed with the creation of a Virtual Host, following the instructions available in this repository.

2.5.3. Create and set an SSL Certificate

If Certbot isn't yet installed on you server, install it and set the SSL certificate for the linkding instance domain (or a subdomain) following the instructions available in this repository. If you already have SSL Certifcates installed on your server with Certbot, you can expand it to include the new domain or you can create a separate certificate for the new domain.

To expand an existing certificate, replace the {LABELS} in the below command as appropriate and execute it.

sudo certbot --apache --cert-name {EXISTING_DOMAIN} --expand -d {EXISTING_DOMAIN} -d {NEW_DOMAIN}

Label Definition

  • {EXISTING_DOMAIN} : The existing domain (or subdomain) that already has a SSL certificate
  • {NEW_DOMAIN} : The new domain (or subdomain) to be included in the existing SSL certificate

Otherwise, to create a separate certificate for the new domain (or subdomain), replace the {LABEL} in the below command as appropriate and execute it.

sudo certbot --apache -d {DOMAIN}

Label Definition

  • {DOMAIN} : The domain (or subdomain) of the new SSL certificate

Restart the Apache Server to apply the updated configuration, executing the following command:

sudo systemctl restart apache2

SSL Labs Server Test can be used to verify the certificate’s grade and obtain detailed information about it, from the perspective of an external service.

To test if the Certbot renewal script includes the new domain (or subdomain), execute the following command:

sudo certbot renew --dry-run

2.5.4. www to non-www redirection

To implement "www to non-www redirection" it's necessary to edit the Virtual Host configuration files (port 80 and port 443). Start with port 443 Virtual Host file generated by Certbot, replace the {LABEL} in the below command as appropriate and then execute it to open the file with the nano text editor.

sudo nano /etc/apache2/sites-available/{VIRTUAL_HOST_FOLDER}-le-ssl.conf

Label Definition

Within the file, replace the {LABELS} in the below snippet as appropriate and then insert it before the proxy config inside the <VirtualHost *:443> block.

# Redirect www.{SUBDOMAIN}.{VIRTUAL_HOST_FOLDER}.{VIRTUAL_HOST_TLD} to {SUBDOMAIN}.{VIRTUAL_HOST_FOLDER}.{VIRTUAL_HOST_TLD}
RewriteEngine On
RewriteCond %{HTTP_HOST} ^www\.{SUBDOMAIN}\.{VIRTUAL_HOST_FOLDER}\.{VIRTUAL_HOST_TLD}$ [NC]
RewriteRule ^ https://{SUBDOMAIN}.{VIRTUAL_HOST_FOLDER}.{VIRTUAL_HOST_TLD}%{REQUEST_URI} [L,R=301]

Labels Definition

  • {SUBDOMAIN} : The subdomain, if applicable, of the new Virtual Host
  • {VIRTUAL_HOST_FOLDER} : The Second-level domain of the new Virtual Host
  • {VIRTUAL_HOST_TLD} : The TLD of the new Virtual Host

After making all the necessary changes, save the file with the command CTRL + O and then exit the nano text editor with the command CTRL + X. Validate the Apache Server configuration with the following command:

sudo apachectl configtest

If the configuration is correct, it's then time to edit the port 80 Virtual Host file. Replace the {LABEL} in the below command as appropriate and then execute it to open the file with the nano text editor.

sudo nano /etc/apache2/sites-available/{VIRTUAL_HOST_FOLDER}.conf

Label Definition

Within the file, delete the totality of it's content. Then, replace the {LABELS} in the below snippet as appropriate and then paste it in the file.

<VirtualHost *:80>

    ServerName {SUBDOMAIN}.{VIRTUAL_HOST_FOLDER}.{VIRTUAL_HOST_TLD}

    ServerAlias www.{SUBDOMAIN}.{VIRTUAL_HOST_FOLDER}.{VIRTUAL_HOST_TLD}

    ServerAdmin {SERVER_ADMIN_EMAIL}

    RewriteEngine on
    RewriteCond %{HTTP_HOST} ^www\.{SUBDOMAIN}\.{VIRTUAL_HOST_FOLDER}\.{VIRTUAL_HOST_TLD}$ [NC]
    RewriteRule ^ https://{SUBDOMAIN}.{VIRTUAL_HOST_FOLDER}.{VIRTUAL_HOST_TLD}%{REQUEST_URI} [L,R=301]

    RewriteCond %{HTTP_HOST} ^{SUBDOMAIN}\.{VIRTUAL_HOST_FOLDER}\.{VIRTUAL_HOST_TLD}$ [NC]
    RewriteRule ^ https://{SUBDOMAIN}.{VIRTUAL_HOST_FOLDER}.{VIRTUAL_HOST_TLD}%{REQUEST_URI} [L,R=301]
</VirtualHost>

Labels Definition

  • {SUBDOMAIN} : The subdomain, if applicable, of the new Virtual Host
  • {VIRTUAL_HOST_FOLDER} : The Second-level domain of the new Virtual Host
  • {VIRTUAL_HOST_TLD} : The TLD of the new Virtual Host
  • {SERVER_ADMIN_EMAIL} : The server's admin e-mail

After making all the necessary changes, save the file with the command CTRL + O and then exit the nano text editor with the command CTRL + X. Validate the Apache Server configuration with the following command:

sudo apachectl configtest

To activate the new Virtual Host, replace the {LABEL} in the below commands as appropriate and then execute it.

sudo a2ensite {VIRTUAL_HOST_FOLDER}.conf
sudo systemctl reload apache2

Label Definition