Confluence on a Raspberry Pi 3 Model B

Yes, you can install Confluence on a Raspberry Pi 3 Model B!

Is it fast? No!

Is it usable? Totally!

Confluence is a fantastic tool — elegant on the surface and complex behind the scenes. At the office, a total newbie can learn the basics and be up and running in 8 minutes. At home, it’s great for capturing organizational data, mostly text and images. Enough about Confluence, though. If you’re reading this, then you are probably wondering how to get it running on a Raspberry Pi. I’ve been running it on a Pi for over a year now, so it definitely works.

Why run Confluence on the Pi?

• Cost – it’s $10 for a Confluence license, $20 for a 64GB microSD card, and a few bucks per year in electricity.
• Safety – after it’s configured you can image the card for an easy restore point and use filesystem-based functionality to create rolling backups.
• Control – it’s locked down to your network as much as you want it to be.
• Challenge – there are some technical hurdles to get it running. It’s a great learning experience in running a resource intensive application on a resource limited device.

What’s covered? In this guide, you’ll see how to configure Confluence (version 6.9.1) and its prerequisites, such as a database (we’ll use MySQL) on the Raspberry Pi Model 3 B. A basic understanding of the Raspberry Pi is assumed, but the basics will be covered at a high level along the way. At the end, there’s an overview of how to restore a previous Confluence backup in the event that you’re migrating to a Pi. In a subsequent post, I’ll review what it takes to spread the server workload out a bit by using a second Pi as the database back-end. By the way, using Confluence to capture repeatable steps like these is a perfect use case and is how I continually updated my trials and errors to a fairly ironed out process.

Prerequisites

There are a few things you’ll need to set up Confluence on the Raspberry Pi.

• Raspberry Pi 3 Model B – I wouldn’t recommend any older version of a Pi
• MicroSD card (8GB minimum, ideally 32GB or 64GB)
• Computer with the ability to write to a microSD card, ideally connected to the same network as the Pi
• Confluence trial licensee (free) or paid license (starts at $10)

Intro

First off, we need a lightweight Linux distro that runs on the Pi. Confluence needs a LOT of memory, so we’ll be shaving off unnecessary services whenever possible. DietPi is a solid, maintained distro that is in many ways similar to the common Raspbian distro. It’s worth noting here that it’s not recommended running Confluence on a Raspbian distro unless you plan on spending a lot of time removing packages (note: I tried this route, it was painful and only marginally successful).

Download and install DietPi for the Raspberry Pi.

1. Download the latest available DietPi image for the Raspberry Pi here.
2. Install the downloaded operating system image onto a microSD card. If you haven’t done this before, it’s much easier than it may sound.
   1. Specific instructions from DietPi
   2. Or instructions from raspberrypi.org:
      1. Windows instructions
      2. Mac instructions
      3. Linux instructions
3. Configure the installation image. DietPi can be pre-configured or post-configured. In this guide, I’ll pre-configure DietPi to reduce the overall number of steps pretty significantly.
   1. After DietPi is written to the microSD card (the previous step), you can make changes to the boot volume on the drive. It’s also easier than it sounds. In Windows, it will auto-mount as a drive letter with a “boot” label. Locate the file dietpi.txt in the root of this drive, open it, and make the necessary changes. Here are the changes I made:

      AUTO_SETUP_NET_USESTATIC=1
      AUTO_SETUP_NET_STATIC_IP=192.168.2.100
      AUTO_SETUP_NET_STATIC_MASK=255.255.255.0
      AUTO_SETUP_NET_STATIC_GATEWAY=192.168.2.1
      AUTO_SETUP_NET_STATIC_DNS=1.1.1.1
      
      AUTO_SETUP_NET_HOSTNAME=Confluence
      
      AUTO_SETUP_AUTOMATED=1
      
      AUTO_SETUP_GLOBAL_PASSWORD=mypasswordhere
      
      AUTO_SETUP_SSH_SERVER_INDEX=-2
      
      AUTO_SETUP_TIMEZONE=America/Denver
      AUTO_SETUP_LOCALE=en_US.UTF-8
      AUTO_SETUP_KEYBOARD_LAYOUT=us
      
      CONFIG_CPU_USAGE_THROTTLE_UP=85
      
      CONFIG_WIFI_COUNTRY_CODE=US

4. Insert the microSD card into the Raspberry Pi and plug it in to turn it on.
5. Log in to the Pi either using a keyboard & monitor directly connected to the Pi or over a network. The default username is root and password is dietpi.
   1. In a terminal window on Linux or Mac, you can simply ssh into the Pi, for example:

      # Change 192.168.2.194 to the IP address of the Raspberry Pi
      ssh [email protected]

   2. On Windows, connect using the popular, free SSH client: PuTTY.
6. If you opted to set it up manually, DietPi launches into it’s setup wizard. If you find yourself at the terminal, it generally shows these commands at the top of the screen, but for reference the following applications can be used to configure DietPi.

   # launch dietpi-config to configure the system
   dietpi-config
   
   # launch dietpi-software to configure software applications
   dietpi-software

7. If you haven’t already, make sure you change the root password (using dietpi-config: Security Options -> Change Root Password).
8. Update the distro to the latest stable changes

9. # The following will update and perform the upgrade. This may take a while.
   sudo apt-get update && sudo apt-get upgrade

10. Install Oracle Java for Linux (NOT OpenJDK)

    # Install Oracle JDK
    sudo apt-get install oracle-java8-jdk

11. Install MySQL

    # This is all it takes to install MySQL
    sudo apt-get install mysql-server

12. Install PHPMyAdmin (optional, usage info not covered in this guide) to test/view MySQL easily. If you don’t have a webserver installed, lighttpd will do the trick (DietPi will prompt for this).

    # You probably could have guessed this by now:
    sudo apt-get install phpmyadmin

13. Edit /etc/mysql/my.cnf. Add this just above the [mysqldump] section. See the official Confluence recommendations here.

    # crd custom
    character-set-server=utf8
    collation-server=utf8_bin
    default-storage-engine=INNODB
    max_allowed_packet=256M
    # If you see log errors, try commenting out the following 2 lines.
    innodb_log_file_size=2G
    innodb_log_files_in_group=7
    innodb_force_recovery=0
    transaction-isolation=READ-COMMITTED

14. Restart MySQL

    /etc/init.d/mysql stop
    
    /etc/init.d/mysql start

15. The final MySQL step is to create a blank database for Confluence and an associated user with sufficient privileges.

    # In the terminal shell
    mysql -u root -p -hlocalhost
    
    # This is in MySQL. 'confluence' is the user we're creating, feel free to change it. Change insertpasswordhere and leave all of the single quotes.
    CREATE DATABASE confluence CHARACTER SET utf8 COLLATE utf8_bin;
    GRANT ALL PRIVILEGES ON confluence.* TO 'confluence'@'localhost' IDENTIFIED BY 'insertpasswordhere';

16. When I initially set this up, manually adjusting the swap file to a larger size (around 1GB) was necessary. At the time of this posting, DietPi defaults to this size when using a 64GB microSD card, so no adjustments appeared to be necessary. To read more about modifying the swap file size on the Raspberry Pi, see this article on BitPi.co. Modification is also conveniently built into the dietpi-config application.
17. Create a dedicated local user to run Confluence

    sudo /usr/sbin/useradd --create-home --comment "Account for running Confluence" --shell /bin/bash confluence

18. At last, time to install Confluence! Note, it MUST be installed from the .tar.gz archive file, not the .bin file. Here’s a reference in case you run into issues, but you can follow the more concise steps outlined below.
    1. Download Confluence 6.9.1 to your home directory (running as root at this point is fine)

       cd /home
       wget https://www.atlassian.com/software/confluence/downloads/binary/atlassian-confluence-6.9.1.tar.gz

    2. Create the installation directory and unarchive the files

       cd /home
       tar -xzf atlassian-confluence-6.9.1.tar.gz -C /home

    3. Download the MySQL connector: mysql-connector-java-5.1.41-bin.jar

       wget -O "/home/atlassian-confluence-6.9.1/confluence/WEB-INF/lib/mysql-connector-java-5.1.41-bin.jar" http://www.craigdugas.com/wp-content/uploads/2018/06/mysql-connector-java-5.1.41-bin.jar

    4. Create a home directory for Confluence

       mkdir /var/confluence-home

    5. Give your dedicated Confluence user read, write, and execute permission to /home/confluence (installation directory) and /var/confluence-home (home directory)

       chown -R confluence /home/atlassian-confluence-6.9.1
       chmod -R u=rwx,go-rwx /home/atlassian-confluence-6.9.1
       chown confluence /var/confluence-home
       chmod -R u=rwx,go-rwx /var/confluence-home

    6. Edit Confluence init properties
       1.  You can use any text editor. A simple one that’s already available on DietPi is nano.

          nano /home/atlassian-confluence-6.9.1/confluence/WEB-INF/classes/confluence-init.properties

       2. At the bottom of the file, add the absolute path to the Confluence home directory

          confluence.home=/var/confluence-home

    7. Before starting Confluence, modify setenv.sh to change Java’s max memory usage to 400M. Anything above this (including the default 1024M) will cause unusable unresponsiveness. This was pure trial and error to find the sweet spot.

       nano /home/atlassian-confluence-6.9.1/bin/setenv.sh
       # Locate and change -Xms1024m -Xmx1024m to -Xms400m -Xmx400m
       
       # Alternatively, you can just run these Linux commands to do the replace:
       sed -i 's/Xms1024m/Xms400m/g' /home/atlassian-confluence-6.9.1/bin/setenv.sh
       sed -i 's/Xmx1024m/Xmx400m/g' /home/atlassian-confluence-6.9.1/bin/setenv.sh

Start Confluence

1. Starting up confluence is pretty straightforward

   sudo su confluence
   cd /home/atlassian-confluence-6.9.1/bin
   ./start-confluence.sh

2. Review the output for success/warning/error messages to ensure Confluence started.
3. At this point you can terminate your terminal session and Confluence will remain running.
4. Navigate to http://ipaddress:8090 to configure your instance. This address is how Confluence will be accessed unless you configure a reverse proxy to access it directly by a domain name.
5. After you configure and log in to Confluence, Collaborative Editing must be disabled, otherwise editing pages will not function.
   1. Click the cog icon -> General Administration -> Collaborative Editing and disable Collaborative Editing.

Migrating an Existing Confluence Instance (Optional)

This part can be tricky. My biggest gripe, by far, with Confluence is that oftentimes restores do not work seamlessly. It seems like this should be the one area where comfort is key, but alas, restoring a previous backup isn’t always point->click->done.

To migrate an existing Confluence instance, you’ll first need a backup archive file from the existing instance. With that in hand, you can perform a restore during the setup process in part 2 of the Start Confluence section above. In my experience, this process often generates odd errors during the restore itself, so proceed with caution.

Here are the steps to restore from a backup during setup:

1. Make sure the version of the existing instance is sufficiently compatible with the new instance. Atlassian tries to maintain a certain level of backwards compatibility. If the backup file is in the same major version as the one you just installed, it should be compatible.
2. If you haven’t taken a backup of the source instance, do so by creating a backup archive (zip) using Confluence’s built in backup feature on the source instance.
3. Copy the archive (SCP/SFTP is easiest) to Confluence’s restore folder (/var/confluence-home/restore)
4. Load the Backup & Restore feature in the Confluence admin section if you’ve already set up Confluence. If you’re restoring during setup, select the option to Restore during the database setup screen.
5. Select the archive to restore. Uncheck Build Index. Restore.
6. Cross your fingers & toes for good luck.
7. After the restore is complete, manually build the index (smaller sites only take 1-2 minutes, even on the Pi).

Additional Customization (Highly Recommended)

Wait, it’s slow?! That’s expected, don’t worry, we’ll address that now. First and foremost, Confluence heavily utilizes caching, so every time you start it up from scratch (e.g. after a reboot), it will be pretty slow. The more you use it, the faster it will run. Don’t be concerned that the first time you click the Spaces drop-down at the top, the system will pause for 10 seconds just to load the simple list. It’ll speed up. Check out the section below on how to speed it up and maintain usable performance.

After setup, if you run htop in the terminal, you’ll see why. Check out the memory usage:

Pushing the Pi to the limit!

Now, for the old school magic tricks. Most items below are done using cron, which you can modify as root from the terminal by running

sudo crontab -e

• As you’re configuring cron, you can use this extraordinarily handy site to create cron schedules https://crontab.guru/#*/10_*_*_*_*
• If you’re inclined, include the lines below as you see fit. The first is essential.
• This line will keep Confluence alive. It’s probably the #1 performance gain I’ve come up with. I suspect behind the scenes Confluence or Java cleans house and those artifacts need to be recreated if you’re not continuously hitting the site.

  # Every 5 minutes - Keep Confluence active
  */5 * * * * wget -O /dev/null http://localhost:8090

• If your backups aren’t enabled, turn them on! This script will clear out backups older than two weeks.

  # 1:30am daily - Remove Confluence backups older than 14 days
  30 1 * * * find /var/confluence-home/backups -type f -mtime +14 -delete

• I’m a stickler with backup & restore strategy. This does a MySQL dump “just in case”. Of course this should be shipped off the Pi to a safe location. You could modify to backup to an ssh output as well.

  # 2:00am daily - Full MySQL backup
  0 2 * * * mysqldump -u root -pYOURPASSWORDHERE --all-databases --events > /var/confluence-home/backups/confluence.pi.mysql.all.databases.sql

• You may want Confluence to start up on boot. Crontab makes it easy

  # Start Confluence on system start
  @reboot sudo runuser -l confluence -c '/home/atlassian-confluence-6.9.1/bin/start-confluence.sh'

• Disable collaborative editing if it’s enabled. It’s a neat feature, but it’s resource intensive.
• Offload MySQL onto a separate Pi or other server. I’ll cover this in the future, it’s super simple to do this. If you have another Pi already running MySQL, such as a web server, then it probably has plenty horsepower to be a back-end for your Confluence instance. Interestingly enough, MySQL isn’t nearly as resource intensive as I expected, but you’ll save 5-10% CPU and a bit of memory by offloading it.
• Installing phpMyAdmin makes MySQL data management a breeze and takes up next-to-no resources on the Pi.

Common issues

• Permissions
  • Refer to the chmod and chown commands above to ensure the directories Confluence will be accessing are owned by the confluence system user account.
  • Ensure you’re running confluence as the confluence system user account and not root.
• Credentials
  • When restoring, for whatever reason my login credentials stop working! Fortunately, Atlassian has a post on restoring admin credentials, though you’ll have to make modifications directly in the database to get this fixed. It’s pretty straightforward.
    • To reset a password, locate an admin user in the confluence database cwd_user table. Then find a similar looking password on the link above which contains hashed versions of the password admin. In the database, replace the password with the new hash, and log in with your username and the password admin. After you’ve successfully logged in, change your password.
• When navigating to Confluence, the site does not load
  • Generally this means an error has occurred behind the scenes. 99% of the time, it’s related to the permissions issues described above. To dig in, look at the logs in /home/atlassian-confluence-6.9.1/logs/catalina.out.
• Editing pages does not work
  • It’s likely that Collaborative Editing is still enabled. Review the step to disable this feature in the Start Confluence section above.

Conclusion

It turns out a Raspberry Pi can be a great device to run a very inexpensive setup for Atlassian Confluence. It became clear that aside from the setup wizard that runs after Confluence started, the entire process can be scripted, which is a work in progress that I’m fine-tuning at this point. If you did set up Confluence on the Pi, I hope you had fun and found the setup process to be successful.