Self-host Wallabag & Archive the Web

Published at July 5, 2020 ·  14 min read

Share on:

Wallabag is an opensource application for saving and archiving web pages. It provides an identical service to bookmarking sites such as Readability, Instapaper, and Pocket.

Save, classify and archive web pages

Save, classify and archive web pages

There are many reasons why Wallabag is an attractive alternative to these commecial services.

Instapaper has changed hands once, Readability was shutdown and Pocket has also changed hands was purchased by the Mozilla Foundation. For those who self-host one driving concern is keeping data on a platform that unsure of its future.

Also, with services like these it’s like storing your browser history on someone else’s computer… Not ideal.

In this tutorial we’re going to walk through setting up Wallabag and Packetriot using Docker. You’ll need Docker installed on your host PC. Since Docker is available for Windows, Mac and Linux this tutorial should cover most users.

We will setup Wallabag using the hostname assigned to your Packetriot tunnel. It’s stable and will not change, so it will work well for a persistently running service.

Using a custom domain or reserved subdomain can also be done and we’ll walk through the small tweaks later in the tutorial. I’ll discuss how to make these changes but it’s important to note that Wallabag doesn’t support multiple hostnames like some other services can.

Let’s get started!

Setting up Wallabag

Below is a Docker compose file with following services: Wallabag, MySQL, Redis and the Packetriot client.

We’ll need to generate some passwords for the Wallabag database and the root password for MySQL. We use the following openssl commands to create some random unique passwords.

[user@host] openssl rand -hex 8
5980ead1a6bbc050

[user@host] openssl rand -hex 8
36de4d81faff3b96

Run this command twice and perform the substitutions in the compose file below.

You can always use passwords that you remember instead of these random values. You will never be enter these passwords beyond the compose file so I would just keep the random passphrases.

This compose file is borrowed from Wallabag’s docker hub. It uses the convention to store images and the underlying MySQL data in /opt/wallabag. We’ll follow the convention and store the Packetriot client configuration in /opt/pktriot.

I would store the compose file in a separate directory, e.g.: /home/user/wallabag. My convention for deploying applications using docker is to put them separate directories. This way I can store the compose file and any other supporting files in one place. It prevents any confusion and is portable.

You can substitute any path values and use your own conventions. However, I wouldn’t skip mounting these paths from the host into the containers because it’ll enable easy backup, migration and updates.

Very important, the value for the environment variable SYMFONY__ENV__DOMAIN_NAME for Wallabag is currently set to https://domain.tld. This value will be updated later in the compose file after we configure our tunnel.

In this setup we’re deploying the Packetriot client alongside Wallabag and it’s dependencies. If you have multiple services you’re self-hosting you will probably want to tweak this setup so you can host more services behind a single client/tunnel.

version: '3'
services:
  wallabag:
    image: wallabag/wallabag:latest
    restart: unless-stopped
    environment:
      - MYSQL_ROOT_PASSWORD=5980ead1a6bbc050
      - SYMFONY__ENV__DATABASE_DRIVER=pdo_mysql
      - SYMFONY__ENV__DATABASE_HOST=db
      - SYMFONY__ENV__DATABASE_PORT=3306
      - SYMFONY__ENV__DATABASE_NAME=wallabag
      - SYMFONY__ENV__DATABASE_USER=wallabag
      - SYMFONY__ENV__DATABASE_PASSWORD=36de4d81faff3b96
      - SYMFONY__ENV__DATABASE_CHARSET=utf8mb4
      - SYMFONY__ENV__MAILER_HOST=127.0.0.1
      - SYMFONY__ENV__MAILER_USER=~
      - SYMFONY__ENV__MAILER_PASSWORD=~
      - SYMFONY__ENV__FROM_EMAIL=email@provider.com
      - SYMFONY__ENV__DOMAIN_NAME=https://domain.tld
    volumes:
      - /opt/wallabag/images:/var/www/wallabag/web/assets/images
  db:
    image: mariadb:latest
    restart: unless-stopped
    environment:
      - MYSQL_ROOT_PASSWORD=5980ead1a6bbc050
    volumes:
      - /opt/wallabag/data:/var/lib/mysql
  redis:
    image: redis:alpine
    restart: unless-stopped
  tunnel:
    container_name: pktriot_wallabag
    image: packetriot/pktriot:latest
    restart: unless-stopped
    volumes:
      - /opt/wallabag/pktriot:/data

Create a new directory called wallabag so we can copy the compose file in it. Start the containers with docker-compose up -d. Below are examples of the commands and their output.

[user@host] mkdir -p wallabag
[user@host] cd wallabag
[user@host:~/wallabag ] ls
docker-compose.yml

[user@host:~/wallabag ] docker-compose up -d
Creating network "wallabag_default" with the default driver
Creating wallabag_redis_1    ... done
Creating wallabag_wallabag_1 ... done
Creating pktriot_wallabag    ... done
Creating wallabag_db_1       ... done

All of the containers should be up and running.

[user@host:~/wallabag ] docker ps
CONTAINER ID        IMAGE                       COMMAND                  CREATED             STATUS              PORTS                             NAMES
db6a16270cec        mariadb                     "docker-entrypoint.s…"   18 seconds ago      Up 17 seconds       3306/tcp                          wallabag_db_1
3800d6322bbe        wallabag/wallabag           "/entrypoint.sh wall…"   18 seconds ago      Up 17 seconds       80/tcp, 0.0.0.0:32770->8080/tcp   wallabag_wallabag_1
4b938aa5ee2b        packetriot/pktriot:latest   "/usr/bin/pktriot --…"   19 seconds ago      Up 17 seconds                                         pktriot_wallabag
14cbbf5c6f7d        redis:alpine                "docker-entrypoint.s…"   19 seconds ago      Up 17 seconds       6379/tcp                          wallabag_redis_1


Packetriot setup and rules

To setup our client in the container we need to run the following command:

[user@host:~/wallabag ] docker exec -it pktriot_wallabag pktriot configure
Choose a path to the configuration file:
[1] /etc/pktriot/config.json
[2] /data/config.json
[3] /root/.pktriot/config.json

Input selection [#]: 2

Authenticate client with login credentials. Created account w/Google SSO? Use --url with 'configure'.

Email: 

Choose option [2] to store the configuration in /data/config.json. This file will be available on your host in the path /opt/pktriot/config.json.

Be sure to chose a region that is closest to you geographically.

Email: user@email.com
Password: 
Authenticated!

Choose the region for the edge server to connect to:
+------------------------+
| #   | Region           |
+------------------------+
| 1   | us-east          |
+------------------------+
| 2   | us-west          |
+------------------------+
| 3   | eu-central       |
+------------------------+
| 4   | asia-southeast   |
+------------------------+
| 5   | australia        |
+------------------------+
| 6   | us-south         |
+------------------------+

Input selection [#]: 1

Tunnel configuration:
  Hostname: autumn-lake-66612.pktriot.net
  Server: us-east-65319.packetriot.net
  IPv4: 159.203.126.35
  IPv6: 2604:a880:800:a1::dd:c001

Start the tunnel and visit URL to check its working:
  pktriot --config /data/config.json start
  https://autumn-lake-66612.pktriot.net

Detailed help and step-by-step tutorials:
  https://packetriot.com/docs
  https://packetriot.com/tutorials.

Need more support?
  Email: packetriot@gmail
  Twitter: @packetriot (please follow us, we like new friends :)

Make a note or copy of the hostname assigned to your tunnel. In our example the hostname assigned to this tunnel is autumn-lake-66612.pktriot.net so we’ll be using it throughout this tutorial.

If you ever need to retrieve this information again run this command:

[user@host:~/wallabag ] docker exec -it pktriot_wallabag pktriot info
Client:
  Hostname: autumn-lake-66612.pktriot.net
  Server: us-east-65319.packetriot.net
  IPv4: 159.203.126.35
  IPv6: 2604:a880:800:a1::dd:c001

We can now create a traffic rule to request HTTPS traffic using the hostname assigned to our tunnel and proxy to our soon-to-be-running Wallabag container.

[user@host:~/wallabag ] docker exec -it pktriot_wallabag pktriot tunnel http add --domain autumn-lake-66612.pktriot.net --destination wallabag_wallabag_1 --http 80

Note, we made the destination for our rule wallabag_wallabag_1 which is the name of our container once its instantiated. Using can use docker ps to confirm the name of the container on your host.

Virtual IP addresses can change when Docker or the host system is restarted, it’s always better to use the name of a container since Docker will resolve it to the containers IP address.

Restart the container, we now ready to update the domain variable in Wallabag container.

Update Wallabag container

Open up the compose file and substitute the hostname for the variable SYMFONY__ENV__DOMAIN_NAME with the hostname assigned to your tunnel. In our case the value will be https://autumn-lake-66612.pktriot.net. We will be hosting Wallabag using https only.

services:
  wallabag:
    image: wallabag/wallabag:latest
    restart: unless-stopped
    environment:
      - MYSQL_ROOT_PASSWORD=5980ead1a6bbc050
      - SYMFONY__ENV__DATABASE_DRIVER=pdo_mysql
      - SYMFONY__ENV__DATABASE_HOST=db
      - SYMFONY__ENV__DATABASE_PORT=3306
      - SYMFONY__ENV__DATABASE_NAME=wallabag
      - SYMFONY__ENV__DATABASE_USER=wallabag
      - SYMFONY__ENV__DATABASE_PASSWORD=ea17ed2a62e7ea2d
      - SYMFONY__ENV__DATABASE_CHARSET=utf8mb4
      - SYMFONY__ENV__MAILER_HOST=127.0.0.1
      - SYMFONY__ENV__MAILER_USER=~
      - SYMFONY__ENV__MAILER_PASSWORD=~
      - SYMFONY__ENV__FROM_EMAIL=email@provider.com
      - SYMFONY__ENV__DOMAIN_NAME=https://autumn-lake-66612.pktriot.net
    ports:
      - "8080"
    volumes:
      - /opt/wallabag/images:/var/www/wallabag/web/assets/images

To reflect this change in the container we need to delete the existing Wallabag container and recreate it. Since our data is stored on the host, via mounted paths, it’s safe. Note, we haven’t really create any data yet.

[user@host:~/wallabag ] docker rm -f wallabag_wallabag_1

This step feels a bit awkward but we have this chicken and egg problem with having to create configure tunnel to get the hostname, then we can complete the Wallabag section in our compose file.

Now run docker-compose up -d in the ~/wallabag directory to recreate it.

[user@host:~/wallabag ] docker-compose up -d

Our Wallabag container is up, let’s test it in out in our browser but visiting the https://autumn-lake-66612.pktriot.net.

Setting up Users in Wallabag

Let’s create our user by visiting our Wallabag instance using the URL https://autumn-lake-66612.pktriot.net. Your hostname will be different. You can click on the register button

Wallabag will want the user to be confirmed via an emailed link. However, we are not setting up email in this installation so we have to confirm the user manually.

We need to step into the container by creating a shell into the Wallabag container and and changing to the /var/www/wallabag directory.

[user@host:~/wallabag ] docker exec -it wallabag_wallabag_1 sh

/ # cd /var/www/wallabag
/ # ls 

CHANGELOG.md        GNUmakefile         README.md           composer.json       docker-compose.yml  scripts             vendor
COPYING.md          Gemfile             RELEASE_PROCESS.md  composer.lock       package.json        src                 web
CREDITS.md          Gemfile.lock        app                 data                phpunit.xml.dist    tests               webpack.config.js
Capfile             Makefile            bin                 docker              postcss.config.js   var                 yarn.lock

The console admin command is bin/console and we will use this to manually activate our newly created user.

This is a work-aorund to setting up email capability in Wallabag. I’m a user and big fan of Mailgun. Their service provides an HTTP API but also an encrypted (TLS) SMTP server with credentials that can be used for configuring email connectivity in web applications like Wallabag.

Let’s enable our user. We’ll first print all of our users and then activate the user we just created.

/var/www/wallabag # ./bin/console -e=prod wallabag:user:list

PHP Warning:  "continue" targeting switch is equivalent to "break". Did you mean to use "continue 2"? in /var/www/wallabag/vendor/doctrine/orm/lib/Doctrine/ORM/UnitOfWork.php on line 2636
PHP Warning:  "continue" targeting switch is equivalent to "break". Did you mean to use "continue 2"? in /var/www/wallabag/vendor/doctrine/orm/lib/Doctrine/ORM/UnitOfWork.php on line 2665
 ---------- --------------------- ------------- ----------- 
  username   email                 is enabled?   is admin?  
 ---------- --------------------- ------------- ----------- 
  wallabag                         yes           yes        
  demo       demo@packetriot.com   no            no         
 ---------- --------------------- ------------- ----------- 

 [OK] 2/2 user(s) displayed. 

Don’t mind these PHP warnings. You will see them in each time we execute a command. This is a warning from PHP, the language Wallabag is written in, warning about the use of a keyword in the language. Ignore…

Our user is here, lets activate it. We will specify the username demo in our command.

/var/www/wallabag # ./bin/console -e=prod fos:user:activate demo

PHP Warning:  "continue" targeting switch is equivalent to "break". Did you mean to use "continue 2"? in /var/www/wallabag/vendor/doctrine/orm/lib/Doctrine/ORM/UnitOfWork.php on line 2636
PHP Warning:  "continue" targeting switch is equivalent to "break". Did you mean to use "continue 2"? in /var/www/wallabag/vendor/doctrine/orm/lib/Doctrine/ORM/UnitOfWork.php on line 2665
User "demo" has been activated.

/var/www/wallabag # 

Now your user is activated. You can now log into the account you just created. Below is a screenshot of your account when you log in the first time.

You can do this for any users that register for the system. It’s important to note that this will be an Internet facing service and bots or random people on the net may try to register. In some sense, this lack of email integration is an mechanism to prevent random people on the Internet from using your Wallabag instance.

There is setting in Wallabag to turn off user registration but it’s outside the scope of this tutorial.

Additional console commands can be found on this page.

Setup the browser extension

The browser extension for Wallabag is very useful and it provides an input field for tagging any pages that you’re archiving. I’m going to step through setting it up on Firefox. It’ will probably follow a similar workflow with other browsers.

You can install the browser extension for the following browsers:

Once you install the extension we need create some API credentials so that the extension can communicate to our Wallabag server. My one pet peeve with this extension is that it requires your password and it is stored in plain-text in your browsers local configuration directory.

This isn’t unlike other passwords that are stored in your browser but I’m putting this note here for your information. I’d suggest not reusing your bank password for Wallabag :)

You’ll need to create a client API token for the extension. Click on the API clients management item in the sidebar and then click on the button Create A New Client. You can provide any name for the client.

You will need to use the Client ID and Client Secret to configure the Wallabag extension.

If things are setup correctly all of the fields will highlight green and it’ll visibly indicate to you that it’s able to connect to your Wallabag instance. Now you’re ready to convenient save and archive web pages!

Using a custom domain

In this section we’ll setup a custom domain. This step is a little different from the earlier section when we setup an HTTPS traffic rule using the hostname our tunnel is assigned.

When using a custom domain you will need to:

  1. Own a custom domain and
  2. Verify ownership of the domain by logging into your Packetriot account

You can do this by logging into your account on packetriot.com and visit the Domains section. Follow these steps to verify the domain.

Once verified you will want to create DNS records for your custom domain. When using the root domain you will want to use an A record and use IP of the Packetriot server you connect to. If you’re using a subdomain then a CNAME record can be used. Use the pktriot info command to print out this information for your tunnel.

Verify that your DNS records were setup correctly. In Linux or macOS you can use the following command to verify that.

[user@host ] dig @1.1.1.1 custom.domain.com

Once those prequiresites are performed we can create an HTTPS traffic rule using Let’s Encrypt for TLS and our custom domain.

[user@host:~/wallabag ] docker exec -it pktriot_wallabag pktriot tunnel http add --domain custom.domain.com --letsencrypt --destination wallabag_wallabag_1 --http 80

Restart the container for the new rule to take affect. It will take 20-30 seconds for Let’s Encrypt to complete it’s challenges and create a set of TLS certificates for your custom domain. The Packetriot client will automatically maintain and keep those certificate up-to-date.

Before we can continue, we need to update the compose file and recreate the container, similar to what we did before.

Updating Compose File

We will need to make a change to our Docker compose file that recreate our Wallabag container. Note, if you’re already setup your container you will need to delete it first.

If you used the compose file as it, minus the necessary substitutions, then the name for the Wallabag container should be wallabag_wallabag_1. Also, if you used mount points then this is a safe operation. If you removed the mount points then you’re potentially risking losing data…

[user@host ] docker ps

[user@host ] docker rm -f wallabag_wallabag_1`

We need to change the value for SYMFONY__ENV__DOMAIN_NAME to our custom domain wallabag.custom.com.

services:
  wallabag:
    image: wallabag/wallabag:latest
    restart: unless-stopped
    environment:
      - MYSQL_ROOT_PASSWORD=5980ead1a6bbc050
      - SYMFONY__ENV__DATABASE_DRIVER=pdo_mysql
      - SYMFONY__ENV__DATABASE_HOST=db
      - SYMFONY__ENV__DATABASE_PORT=3306
      - SYMFONY__ENV__DATABASE_NAME=wallabag
      - SYMFONY__ENV__DATABASE_USER=wallabag
      - SYMFONY__ENV__DATABASE_PASSWORD=ea17ed2a62e7ea2d
      - SYMFONY__ENV__DATABASE_CHARSET=utf8mb4
      - SYMFONY__ENV__MAILER_HOST=127.0.0.1
      - SYMFONY__ENV__MAILER_USER=~
      - SYMFONY__ENV__MAILER_PASSWORD=~
      - SYMFONY__ENV__FROM_EMAIL=email@provider.com
      - SYMFONY__ENV__DOMAIN_NAME=https://custom.domain.com
    ports:
      - "8080"
    volumes:
      - /opt/wallabag/images:/var/www/wallabag/web/assets/images

Now we can recreate the container.

[user@host ] cd ~/wallabag

[user@host:~/wallabag ] docker-compose up -d

We’re done with setting up Wallabag with our custom domain. The Packetriot client will maintain our certificates from Let’s Encrypt which removes one thing to worry about.

Using a reserved subdomain

Users with paid accounts are provided a varied numbef of subdomains that can be reserved from the domains managed by Packetriot. Reserved these domains is simple, visit the Subdomains section after logging into packetriot.com.

Once there choose and reserve a subdomain, e.g. my-wallabag.pktriot.net.

You will need to performed steps similar to what we did with custom domains in the section above. However, you will need to use Let’s Encrypt. Instead the traffic rule will use the subdomain you reserved.

We’ve provided an example below.

[user@host:~/wallabag ] docker exec -it pktriot_wallabag pktriot tunnel http add --domain my-wallabag.pktriot.net --letsencrypt --destination wallabag_wallabag_1 --http 80

You will need to restart the container to let the rule take affect and be sure to update the compose file and substitute the value for the domain name used for your Wallabag server. You will need to delete and re-create the container.

Software Updates

With this installation keeping up with software should be easy, this is because all of our application data for all of our contains (Wallbag, Packetriot, MySQL) is being stored on the host, not inside the container.

Below are commands you can run to refresh all the software for all of the containers.

[user@host ] cd ~/wallbag

# remove exisitng containers
[user@host:~/wallabag ]

# pull down updates
[user@host:~/wallabag ]

# recreate the containers
[user@host:~/wallabag ] docker-compose up -d

Conclusion

I would highly recommend Wallabag to anyone that may be using alternatives like Pocket or Instapaper. It took some work to get Wallabag setup but we covered custom domains, reserved subdomains, and the browser extension which I recommand with the cavaeat to not reuse a sensitive password.

Please contact us if you have any questions or run into any trouble, we’ll do our best to help. We did not cover all options and configurations for Wallabag but we did provide enough information to setup and administer it.

We hope you enjoyed this tutorial, please share if this was helpful and follow us on Twitter @packetriot for updates and notifications when we write another self-hosting tutorial.

Cheers!