Readplace

Documentation

Readeck 3 min read
View original
Crawl details
  • Current
Summary (TL;DR)
Readeck installs as a single executable with no dependencies and runs on Linux, FreeBSD, MacOS, or Windows. It needs any 64-bit Intel, AMD, or ARM CPU, 512 MB of memory, and around 200 MB of storage, plus roughly 300 kb per saved bookmark. Docker or Podman works for a quick test, and the docs include a one-line docker run command that creates a readeck-data volume. Binary installs mean downloading the file for your system, making it executable, then running ./readeck serve. The app is reachable at http://localhost:8000/ on first launch. Upgrades swap the binary or pull the latest image, then restart.

Security notes say not to run Readeck as root. The recommended Systemd service uses a dedicated user and drops unneeded capabilities. The container image has no defined user, so it runs as root inside unless you pass a --user flag like 1000:1000. Rootless container engines do not require a user, but keeping file ownership means handling subuid and subgid mapping.

Welcome!

Thank you for your interest; this page will guide you through the installation process. I hope you enjoy using Readeck as much as I enjoy building it!

User Documentation

The User Documentation is embedded in Readeck so it's easy to access and always up-to-date.
You can, however, read the user documentation in the code repository if you'd like to have a peek on Readeck before installation.

Installation Requirements

Readeck consists of a single executable file with no dependencies. Any common computer you have around is probably more than capable of running the app.

Here are the resources needed:

  • Operating System: Linux, FreeBSD, MacOS or Windows.
  • CPU: Any 64-bit Intel, AMD or ARM CPU than can run the Operating Systems above.
  • Memory: 512 MB. — It uses less than that but can peak when processing content's images.
  • Storage: 200 MB would already take you a long way. You can count about 300kb for each bookmark you save.

Tip

Readeck will perform well enough on the old RaspberryPi 2 you forgot in a drawer.

If your Operating System is not listed above, you can most likely compile Readeck for it.

Installation

With Docker or Podman

Readeck can easily run in a container using docker or podman. For a quick preview, here's the docker command:

docker run --rm -ti -p 8000:8000 -v readeck-data:/readeck codeberg.org/readeck/readeck:latest

Tip

This will create a volume readeck-data that contains the database and the bookmark files. You can, of course, mount a folder as a volume if you prefer.

You can find all the released Readeck images on https://codeberg.org/readeck/-/packages/container/readeck/latest.

For a more production ready installation, check out the Compose Files documentation.

Binary file installation

Readeck is distributed as a single binary file. Using it is almost as straightforward as a container.

Open a terminal and go to a newly created directory:

mkdir -p readeck-install
cd readeck-install

Download the file matching your system and name it readeck (or readeck.exe on Windows).

For example, on a standard Linux system with an Intel or AMD CPU, you can download the latest release this way:

wget -O readeck https://codeberg.org/readeck/readeck/releases/download/0.23.4/readeck-0.23.4-linux-amd64
chmod a+x readeck

Launch Readeck with the serve argument:

./readeck serve

First time launch

Once Readeck has started, it is accessible on:
http://localhost:8000/

Upgrade

A simple process

The upgrade consists of swapping the executable or container image by the latest one and restart Readeck. The upgrade process, if any, runs when you restart the server.

Upgrading the container version

This is the easiest; run:

docker pull codeberg.org/readeck/readeck:latest

And then restart the container running the image.

Upgrading the binary release

Stop Readeck, Download the latest release and replace the currently running binary on your server. Then start Readeck.

Security considerations

Single file executable

Do not start Readeck as a privileged user (root).

The recommended Systemd service runs Readeck as a specific user and drops unnecessary capabilities and system calls.

Container

Readeck's container image doesn't define a user (Readeck then runs as root inside the container) and it's up to you to decide if and how you want to change the container user, especially when using rootful containers. You're in charge but here are a few recommendations:

Readeck on a rootfull container engine

Start the container with a --user parameter, for example --user 1000:1000.

Readeck on a rootless container engine

You don't have to provide a user but you can. If you do so and want to retain file ownership, you'll need to deal with subuid and subgid mapping.