The objective is to install Paperwork on Ubuntu 18.04 Bionic Beaver

Operating System and Software Versions

  • Operating System: - Ubuntu 18.04
  • Software: - Paperwork 1


Privileged access to the operating system




  • # - requires given linux commands to be executed with root privileges either directly as a root user or by use of sudo command
  • $ - given linux commands to be executed as a regular non-privileged user


Paperwork is a note-taking and archiving alternative to Evernote, Microsoft OneNote, and Google Keep, with the advantage of being FOSS (Free and Open Source Software), meaning it that can be hosted on the user premises, which is a requirement for people and businesses worried about privacy.

Paperwork is comprised of collections that contain notebooks of notes. Notes can be shared with other users. Tags can be assigned to notes that can also have documents attached to them. The user interface has translations to 23 languages. It’s also worth mentioning that there is an API that is useful for integration with other software.

The project web page mentions that version 2 is a major rewrite that is at an early development stage, meaning it's not usable yet. While we wait for the shiny new version, we’ll cover how to have version 1 running on the latest Ubuntu LTS release.

Version 1 was released in 2014 and is written in the LEMP stack (Linux, Nginx, MySQL, PHP) using Laravel 4 framework and other Web technologies, like AngularJS and Bootstrap.

For this article we first tried to build a docker image, using the docker-compose file listed in the project’s Git repository, but the build is broken in multiple ways. We then reverted to the conventional form of installation, adapting the 16.04 manual for installing Paperwork in Ubuntu to version 18.04, and it proved to be a rather long, but easy sequence of steps to follow. The major setback is that 18.04 Bionic Beaver comes with a newer PHP (version 7.2) and the extension mcrypt has been deprecated and moved to PEAR (a repository of PHP code) -- but you will see that this difficulty can be easily overcome.

Before committing few hours to have your own instance running, it may be worth having a taste of Paperwork at a cloud-hosted provider, namely Sandstorm or Cloudron.

Once you're ready to install Paperwork, notice that the steps below assume a clean installation of Ubuntu Server 18.04 Bionic Beaver. For Ubuntu Desktop the guide will be almost the same, except for the first step.


Add Universe Repository

For Ubuntu Server, you have to add the Universe repository to install some packages (npm, nodejs, php-mbstring). Ubuntu Desktop already has the Universe repository enabled so this step can be skipped.
# add-apt-repository universe

Install package dependencies.

It will download 87.1 MB which will use 449 MB of disk space. Here we notice some differences from the set of packages required for 16.04.
# apt install wget git npm zip libmcrypt-dev mysql-server php-mysql nginx php-fpm curl php-cli php-gd nodejs php-xml php-mbstring php-pear php-dev

Install mcrypt

The mcrypt PHP extension has long been abandoned and has been moved to PEAR. As it’s a dependency for Paperwork version 1, it needs to be installed with pecl.
sudo pecl channel-update pecl.php.net
sudo pecl install mcrypt-1.0.1 (when asked, just press enter)
You also have to add extension mcrypt.so to php.ini for both, the cli and fpm instances. Two methods are shown below. Notice that php-fpm will only load (and be aware of) mcrypt after it’s reloaded in step 13. Adjust the below PHP version number where appropriate.
# sed -i.bak '927iextension=mcrypt.so' /etc/php/7.2/cli/php.ini
# sed -i.bak '927iextension=mcrypt.so' /etc/php/7.2/fpm/php.ini
# pico /etc/php/7.2/cli/php.ini
# pico /etc/php/7.2/fpm/php.ini
	Add extension=mcrypt.so

Install composer

Composer is a dependency manager for PHP.
curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer

Download Paperwork

Download Paperwork from GIT.
# cd /var/www/html/
# git clone -b 1 https://github.com/twostairs/paperwork.git

Function mcrypt_get_iv_size deprecated

Besides the entire mcrypt extension, the function mcrypt_get_iv_size has also been deprecated. As a consequence, an error message will be thrown later into the user interface when the application is accessed by the browser. We must instruct PHP ignore it by adding a line to app/config/app.php.
# cd paperwork/frontend/
# sudo sed -i.bak '3ierror_reporting(E_ALL ^ E_DEPRECATED);' \
# app/config/app.php

Prepare the database

Create the database and a database user
# mysql
GRANT ALL PRIVILEGES ON paperwork.* TO 'paperwork'@'localhost' IDENTIFIED BY 'paperwork' WITH GRANT OPTION;

Populate the database

When asked, answer with “y”.
# php artisan migrate

Install PHP dependencies

Install PHP dependencies through composer.
# composer install

Install gulp and bower

Then install npm and bower dependencies.
sudo npm install -g gulp bower
sudo npm install
sudo bower install --allow-root
sudo gulp

Change the ownership of files

Change the ownership of Paperwork directory to www-data.
sudo chown www-data:www-data -R /var/www/html/

Nginx configuration

Edit or replace Nginx default site.

# pico /etc/nginx/sites-available/default
server {
        listen   80;
        # listen 443 ssl;

        root /var/www/html/paperwork/frontend/public;
        index index.php index.html index.htm;

        server_name example.com;

        # server_name example.com;
        # ssl_certificate /etc/nginx/ssl/server.crt;
        # ssl_certificate_key /etc/nginx/ssl/server.key;

        location / {
                try_files $uri $uri/ /index.php;

        error_page 404 /404.html;

        # pass the PHP scripts to FastCGI server listening on the php-fpm socket
        location ~ \.php$ {
                try_files $uri =404;
                fastcgi_pass unix:/var/run/php/php7.2-fpm.sock;
                fastcgi_index index.php;
                fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
                include fastcgi_params;



Restart services

Restart Nginx and PHP.
$ sudo service nginx restart
$ sudo service php7.2-fpm restart

Access Paperwork

Now you can open Paperwork in your browser using localhost if the installation is local, or the IP address of the machine where it is installed. You should see a welcome page that initiates the setup wizard.

Run the Wizzard

First, the wizard checks that all dependencies and assets are in place. Then it sets the database connection (server, port, username, password, database). Next, it will ask for the definition of some system settings. And, finally, it will ask for the registration of the first user account.


Login with the newly created user account, and happy note-taking!
Paperwork Main Screen
Paperwork application interface after login


Paperwork is being rewritten from scratch, with different technologies (mostly Javascript), and will be completely different than version 1. While we wait, version 1 can be installed in Ubuntu 18.04 Bionic Beaver by following a long, but easy sequence of commands to follow.

In the end, Paperwork is a great FOSS alternative to proprietary software that can be installed on the user premises. It has some interesting features and let us excited waiting for the next version.
Submit your RESUME or create a JOB ALERT on LinuxCareers.com job portal.
Get extra help by visiting our LINUX FORUM or simply use comments below.

You may also be interested in:

Comments and Discussions