Paperback blog

Well hello again old friend,

I hope time has treated you as best it can and that you’re managing through the pandemic in OK shape.

I’ve spent much of the spare time I had in 2020 working on a complete rewrite of the Paperback code base and I’m happy to relaunch it today. Paperback continues to have the simple utility you’ve come to love with a solid new foundation. Grab a drink and let me tell you a bit about it.

[Skip ahead to the part where I tell you about the features]

A lot has changed in and around the web since I started Paperback in 2013 and yet much remains the same. Snowden had just given an archive of classified NSA documents to journalists, much which would continue to be reported on over the next several years. This led to a recognition of both state and corporate surveillance at levels previously unimaginable. Plain Javascript went out of style only to come back into style a few years later. Monoliths have been torn apart into unmanageable pieces only to be stitched back together and deployed into unmanageable clusters. The world of containerized server infrastructure slowly moved in like a whale, filling up developer hard drives and servers around the globe.

Both change and time can be good and bad and it’s up to us to find the good and bad in it all.

Virtual private servers are great for small and medium size projects. Having to keep a VPS up-to-date is not good fun when you just want your software to run effortlessly.

Containers are good for keeping the interface of your code consistent across environments but are a pain in the ass if aren’t configured and deployed correctly.

Using third-party packages helps to not add more code and more bugs but dependencies are painful to manage if you’re not actively trying.

Not losing customer data is good but keeping customer data around forever is not good.

The technology I used for the rewrite generally doesn’t matter to customers. I could have built the same features using any stack out there. It all came down to my own preference and the amount of time and energy I can put into a hobby project. I won’t make any sweeping arguments for or against any system. I just want to share my thought process on how I designed this system around a few core things:

• A low-cost, low-maintenance container hosting mechanism that doesn’t require crazy things like load balancers or ingress controllers just to access the server
• Simple HTML, CSS, and JS that’ll mostly look the same in 10 years for an app that works as well in w3m as it does in a home screen PWA
• A storage mechanism that respects my customers’ privacy and makes it easier for me to discard data than it does to keep it forever

What I ended up with:

• A Flask app for server-side HTML with vanilla JS for any interactivity
• Turbolinks for some SPA-like navigation and client-side caching features
  • When writing this I learned that Turbolinks is no longer under active development and is being replaced by Turbo but thanks to it’s minimal integration points takes only two lines of code to migrate
• Workbox to help with some service worker caching to get offline support
• RQ to help offload some slow running tasks and requests (Maciej, if I can lend a hand with API performance I have some PHP P.P.E on standby)
• Redis to cache Pinboard and article data, all using a default but customizable expiry time so there isn’t any bit clutter
• Postgres for storing as little customer data as possible like account information and settings
• Tied together using docker compose
• Deployed using docker stack deploy and the docker context feature
• To a VPS running RancherOS for no-maintenance hosting

This is by no means novel or interesting and continues to support one of my original values: “Simple, proven technology; Nothing fancy to see here”. Server-side HTML + Redis + Postgres is the most boring combination ever, which is perfect for me. The more “innovative” parts that I found useful was deploying containers to RancherOS. I’ve long been a fan of boring old virtual private servers and have gotten comfortable over the years configuring and maintaining them. They’re cheap and are workhorses. It has taken a while for containers to become simplified enough for me to go all-in but the coming together of docker-compose with contexts and running a VPS with RancherOS has been the sweet spot for me. I can run a system that’s replicable and scalable, managed in code, with zero server configuration necessary for $5 a month. These are very nice upgrades from having to spin up apache myself.

The last major revision of Paperback used the original PHP-based back end but I had built the app using Angular (before it became the legacy Angular.js). Even at the time of first building the single page app in 2014, I felt pretty uncomfortable with it. The documentation was bad, there wasn’t much on Stack Overflow that helped me out, and I just generally felt like I was walking around in the dark. But at the time I felt resigned to the fact that it was how web apps had to be built to perform well. I continued to add small features bit by bit within the existing architecture but started to feel very limited by the aging and outdated PHP framework I was using and front-end tools I didn’t know how to use. I was happy to tear it all down and start fresh with a bit of regret for my misteps of 2014 (the year the web started dying).

I feel much more comfortable now getting back to basics and knowing that I have an infrastructure I can evolve more easily. It’s another important lesson in picking tools that are right for the job and make a healthy impact.

In America and around the world, we’re going to have to do a lot of rebuilding in 2021. We need to be thinking about how to build back something that’s better than where we’ve been. Something that’s simplified down to the important parts of making peoples’ lives better and more equitable while reducing and repairing the damage we’ve done to our natural ecosystems and climate, and thinking a few steps ahead so we make thoughtful and logical but swift and meaningful progress.

New Features

Here are the highlights:

New data retention policy

By default cached data like unread list from Pinboard or the URL and contents of articles are only stored for 90 days, then they expire. The benefit of this for customers is they don’t have to worry about their data lingering around forever. Most companies work very hard to keep your data forever, whether they use it or not. I’ve designed this update around you having the data you need quick and handy when you need it and gone when you want it. This expiry is configurable so you can make it shorter or longer.

Basic offline support in modern browsers

Most browser now support the ability to cache pages and assets for online use. Paperback now supports seeing your reading list and articles offline. Updating information or actions like marking articles as unread are disabled until and can be done once online again.

If you have Paperback open in a tab in Safari on iOS, you’ll be able to access articles again offline. To make sure Paperback is always accessible offline, add it to your home screen.

Tag-based reading list

You can now use a tag to define your reading list instead of using Pinboard’s “to read” list. Defined in Settings, Paperback’s reading list will be any item with that tag. When you mark the article as read Paperback will remove the tag for you.

Less Popular

Pinboard’s Popular page is great but has lots of stuff I’m not interested in. Paperback has a Popular page but allows you to filters out domains or keywords so you can keep up with what’s hot and stay anti-social.

So many newsletters

I’ve enjoyed the renaissance of newsletters but email apps don’t provide great reading experiences. With this new feature, you get a special address that you can forward emails to. Paperback will host a permanent web page with the HTML of the email, add the link to Pinboard, and parse the email content in your reading list. If you forward as an attachment, you can use the body of the email to add a description to the pin and Paperback will try to parse the headers of the attached email and pin the List-Post URL, if it exists. This works with platforms like Substack to let you pin the Substack permalink instead of the Paperback-hosted HTML page.

Definition lookup

Just selected a word in an article and Paperback will look up the definition. Work on your vocabulary without having to copy/paste.

PDF exports

Export beautiful PDFs for longterm storage or print for offline reading. If you have any highlights, they will be included in the PDF. You’ll get an email with a link to the PDF to download.

See the new Welcome page and the full feature overview.

If you ever have any questions or feature requests, feel welcome to email me at support@readpaperback.com.

Log in to start reading smarter.

Yours in unity,
–Nick