Image CDNs make it easy to dynamically optimize the aesthetics and performance of your images. Unlike most image CDNs, Thumbor is open-source and can be used for free to resize, compress, and transform images. It’s suitable for production use; Wikipedia and Square both use Thumbor.
This guide explains how to install Thumbor on your own server. Once installed, you’ll be able to use Thumbor as an API for transforming your images.
Intro #
You’ll be installing Thumbor on a VM running Ubuntu 16.04. Ubuntu 16.04 is a very common image and these instructions are intended to work on any cloud provider. Creating a VM might sound like more work than installing Thumbor on your local machine, but the minutes that you take to create a VM will probably save you hours or days of frustration trying to get Thumbor to properly install on your local machine. Although easy to use, Thumbor is notoriously difficult to install but these instructions simplify the process. If dependencies download quickly, the installation can be completed in 5 to 10 minutes.
Prerequisites #
This post assumes that you know how to create a Ubuntu 16.04 LTS VM on a cloud platform like Google Cloud, AWS, or Azure and how to use command line tools to set up the VM.
Install Thumbor Dependencies #
Update and upgrade Ubuntu’s already-installed packages:
sudo apt-get update -y && sudo apt-get upgrade -y
Install pip, the package manager for Python. Later you’ll install Thumbor with pip.
sudo apt-get install -y python-pip
Install Thumbor’s dependencies. Thumbor’s documentation does not explicitly mention these dependencies, but Thumbor will not install successfully without them.
# ssl packages
sudo apt-get install -y libcurl4-openssl-dev libssl-dev
# computer vision packages
sudo apt-get install -y python-opencv libopencv-dev
# image format packages
sudo apt-get install -y libjpeg-dev libpng-dev libwebp-dev webp
Install Thumbor #
Install Thumbor using pip.
sudo pip install thumbor
Note: Many Python developers use virtualenv to manage their packages. For the sake of simplicity, these instructions do not use virtualenv. If you are installing Thumbor in a standalone environment, virtualenv is not necessary. If you choose to use virtualenv, note that Thumbor requires Python 2.7 and will not work with newer versions of pip (e.g., these instructions use pip 8.1.1).
If you’ve successfully installed Thumbor, this should work:
thumbor --help
Run Thumbor #
Run Thumbor. Debug logging is optional but can be helpful when you’re getting started.
thumbor --log-level debug
Thumbor is now running.
Open Firewall Port #
By default, Thumbor runs on port 8888. If your VM’s IP address is 12.123.12.122, then you would access Thumbor from the web browser at http://12.123.12.123:8888/.../$IMAGE.
However, this probably won’t work for you (yet) because cloud providers usually require that you explicitly open firewall ports before they will accept incoming traffic.
Update the firewall to expose port 8888. Here’s more information on how to do this for: Google Cloud, AWS, and Azure. Note that for Google Cloud you need to first assign a static IP address to your VM and then allow an external HTTP connection.
Try It Out #
Thumbor is now accessible and ready for use. Try it out by visiting the following URL:
Note that this URL uses HTTP. Thumbor uses HTTP by default but can be configured to use HTTPS.
You should see an image that is 100 pixels wide by 100 pixels tall. Thumbor has taken the image hero.jpg and size specified in the URL string and served the result. You can replace the image in the URL string (i.e., https://web.dev/install-thumbor/hero.jpg) with any other image (e.g., https://your-site.com/cat.jpg) and Thumbor will resize that image too.
The Optimize images with Thumbor article has more information on using the Thumbor API. In particular, you may be interested in setting up a Thumbor configuration file.
Appendix: Configuring Systemd #
This step explains how to make sure that the Thumbor process keeps running, even after the VM has been restarted. This step is important for production sites, but optional if you’re just playing around with Thumbor.
Systemd is the “system and service manager” for Linux operating systems. systemd makes it easy to configure when services (processes) run.
You will be configuring systemd to automatically start Thumbor on VM boot. If the VM is restarted, the Thumbor process will automatically restart as well. This is much more reliable than relying on user intervention to start Thumbor.
Navigate to the /lib/systemd/system directory. This directory contains the service files for systemd.
cd /lib/systemd/system
As superuser, create a thumbor.service file.
sudo touch thumbor.service
Using your favorite text editor (vim and nano come pre-installed on Ubuntu or you can install another editor), add the following configuration to thumbor.service. This configuration will run /usr/local/bin/thumbor (i.e. the Thumbor binary) once networking is available and will restart Thumbor on failure.
[Unit]Description=Service for Thumbor image CDN
Documentation=https://thumbor.readthedocs.io/en/latest/
After=network.target
[Service]
ExecStart=/usr/local/bin/thumbor
Restart=on-failure
[Install]
WantedBy=multi-user.target
systemctl is the utility used to manage systemd. Use the start command to start Thumbor.
sudo systemctl start thumbor.service
Note: If Thumbor is currently running, you should stop it before attempting to start Thumbor using systemctl.
Next, “enable” Thumbor. This means that Thumbor will automatically start on boot.
sudo systemctl enable thumbor.service
Verify that you’ve successfully configured systemd by running the status command.
systemctl status thumbor.service
If you’ve successfully set up thumbor.service to use systemd, the status should show that it is enabled and active.