README
¶
Readeck
Readeck is a simple web application that lets you save the
precious readable content of web pages you like and want to keep
forever.
See it as a bookmark manager and a read later tool.
Contents
Features
🔖 Bookmarks
Like a page you're reading? Paste the link in Readeck and you're done!
📸 Articles, pictures and videos
Readeck saves the readable content of web pages for you to read later. It also detects when a page is an image or a video and adapts its process accordingly.
⭐ Labels, favorites, archives
Move bookmarks to archives or favorites and add as many labels as you want.
🖍️ Highlights
Highlight the important content of your bookmarks to easily find it later.
🗃️ Collections
If you need a dedicated section with all your bookmarks from the past 2 weeks labeled with "cat", Readeck lets you save this search query into a collection so you can access it later.
🧩 Browser Extension
Want to keep something for later while browsing? No need to copy and paste a link. Install the browser extension and save bookmarks in one click!
📖 E-Book export
What's best than reading your collected articles on your e-reader? You can export any article to an e-book file (EPUB). You can even export a collection to a single book!
On top of that, you can directly access Readeck's catalog and collections from your e-reader if it supports OPDS.
🔎 Full text search
Whether you need to find a vague piece of text from an article, or all the articles with a specific label or from a specific website, we've got you covered!
🚀 Fast!
Readeck is a modern take on so called boring, but proven, technology pieces. It guaranties very quick response times and a smooth user experience.
🔒 Built for your privacy and long term archival
Will this article you like be online next year? In 10 year? Maybe not; maybe it's all gone, text and images. For this reason, and for your privacy, text and images are all stored in your Readeck instance the moment you save a link.
With the exception of videos, not a single request is made from your browser to an external website.
How to test or install
Done reading this promotional content? Good! Want to try Readeck on your laptop or a server? Even better!
Container
To install or test Readeck with Docker or Podman, simply run the image:
docker run --rm -ti -p 8000:8000 -v readeck-data:/readeck codeberg.org/readeck/readeck:latest
You'll find all the container images there:
https://codeberg.org/readeck/-/packages/container/readeck/latest
Binary file installation
Readeck is distributed as a single binary file. Using it is almost as easy as a container.
-
Create a new directory
mkdir -p readeck-install cd readeck-install -
Download the file matching your system from the last release
-
Make this file executable
-
Launch Readeck with the
serveargument, for example:./readeck-0.9.1-linux-amd64 serve
First time launch
Once Readeck has started, it is accessible on:
http://localhost:8000/
Installation for production
More documentation is coming but if you already know how deploy containers or new services on a server (ie. with systemd), it should be quite straightforward.
FAQ
I can't save a link or it's incomplete
Readeck usually can save the vast majority of news or blog articles but it sometimes fails to do so. The most common reasons are:
- The page is behind a paywall,
- The page needs JavaScript to render its content,
- Your server is blocked,
- The content extractor fails.
The most common solution to these problems is to install and use the Browser Extension. The extension sends the page's full content to Readeck, so anything can be saved. Moreover, it lets you select the exact content you want to save.
If a page really doesn't work at all, please open an issue.
Can I share a saved bookmark with a public link?
Yes you can, for a limited time. On each article you can generate a link that'll be valid for 24 hours. You can generate a new link as many times as you want but it will always expire. You can also export or print an article to a PDF file.
Is there a system to store my (paywall) website credentials?
There isn't, for several reasons:
- To safely store credentials without giving access to anyone but the user is next to impossible,
- Such a system relies on web scrapping and is prone to break too often,
- It might go against websites TOS.
Again, the Browser Extension will let you save any content you can access from your web browser.
Is there a roadmap?
There are milestones, where you can see what's planned for the future releases.
For longer term goals, there are projects
Is there a Readeck twitter account?
There isn't but you can follow @readeck@mastodon.online on Mastodon.
Is the a Readeck Discord server?
There isn't but you can join #readeck:matrix.org on Matrix.
How can I report a security issue?
If you think you found a security issue in Readeck, please DO NOT create an issue; they're public and it could potentially put all users at risk.
Send an email to security@readeck.com and you'll receive a follow-up as soon as possible.
Under the hood
Readeck was born out of frustration (and COVID lock-downs) from the tools that don't save everything related to the saved content, primarily images. This key principle guided every step of Readeck development.
The ZIP file
Every bookmark is stored in a single, immutable, ZIP file. Parts of this file (HTML content, images, etc.) are directly served by the application or converted to a web page or an e-book when needed.
A simple database
Readeck has a very simple database schema with a few tables (and a bit of clever JSON fields here and there). The recommended database engine is SQLite for most installations.
A simple stack
Unlike many modern web applications, Readeck is not a single page application built on top of an API with impossible to install dependencies and a mess of background processes.
Readeck is written in Go and all its content is rendered server side with some interactivity brought by Stimulus and Turbo.
This has proven to be a great combination when performance really matters.
License
Readeck is distributed under the terms of the GNU Affero General Public License v3.0. Here's a short summary of the license conditions:
- Permissions
- Commercial use
The licensed material and derivatives may be used for commercial purposes. - Distribution
The licensed material may be distributed. - Modification
The licensed material may be modified. - Patent use
This license provides an express grant of patent rights from contributors. - Private use
The licensed material may be used and modified in private.
- Commercial use
- Conditions
- Disclose source
Source code must be made available when the licensed material is distributed. - License and copyright notice
A copy of the license and copyright notice must be included with the licensed material. - Network use is distribution
Users who interact with the licensed material via network are given the right to receive a copy of the source code. - Same license
Modifications must be released under the same license when distributing the licensed material. In some cases a similar or related license may be used. - State changes
Changes made to the licensed material must be documented.
- Disclose source
- Limitations
- Liability
This license includes a limitation of liability. - Warranty
This license explicitly states that it does NOT provide any warranty.
- Liability
Documentation
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package assets contains Readeck's static files and templates.
|
Package assets contains Readeck's static files and templates. |
|
Package configs contains Readeck configuration.
|
Package configs contains Readeck configuration. |
|
Package docs handles Readeck's documentation files and HTTP routes.
|
Package docs handles Readeck's documentation files and HTTP routes. |
|
internal
|
|
|
acls
Package acls defines a simple wrapper on top of casbin functions.
|
Package acls defines a simple wrapper on top of casbin functions. |
|
admin
Package admin contains routes and tasks for Readeck admin.
|
Package admin contains routes and tasks for Readeck admin. |
|
app
Package app is Readeck main application.
|
Package app is Readeck main application. |
|
assets
Package assets provides the HTTP routes that serve static files.
|
Package assets provides the HTTP routes that serve static files. |
|
auth
Package auth defines Readeck's authentication providers.
|
Package auth defines Readeck's authentication providers. |
|
auth/credentials
Package credentials contains the models and functions to manage user credentials.
|
Package credentials contains the models and functions to manage user credentials. |
|
auth/onboarding
Package onboarding provides the routes and forms for the initial onboarding process.
|
Package onboarding provides the routes and forms for the initial onboarding process. |
|
auth/signin
Package signin contains the routes for Readeck sign-in process.
|
Package signin contains the routes for Readeck sign-in process. |
|
auth/tokens
Package tokens contains the models and functions to manage user API tokens.
|
Package tokens contains the models and functions to manage user API tokens. |
|
auth/users
Package users contains the models and functions to manage users.
|
Package users contains the models and functions to manage users. |
|
bookmarks
Package bookmarks provides storage and tooling for bookmarks and collections management.
|
Package bookmarks provides storage and tooling for bookmarks and collections management. |
|
bookmarks/importer
Package importer provides the necessary tooling to import bookmarks from various sources.
|
Package importer provides the necessary tooling to import bookmarks from various sources. |
|
bookmarks/routes
Package routes provides http routes for bookmarks and collections management.
|
Package routes provides http routes for bookmarks and collections management. |
|
bookmarks/tasks
Package tasks contains the bookmark and collection related tasks.
|
Package tasks contains the bookmark and collection related tasks. |
|
bus
Package bus provides Readeck's message bus and task executor.
|
Package bus provides Readeck's message bus and task executor. |
|
cookbook
Package cookbook provides routes for testing and design previews.
|
Package cookbook provides routes for testing and design previews. |
|
dashboard
Package dashboard provides routes for Readeck's dashboard.
|
Package dashboard provides routes for Readeck's dashboard. |
|
db
Package db provides the first layer interfaces to database storage.
|
Package db provides the first layer interfaces to database storage. |
|
db/filters
Package filters provides query filters for specific operations.
|
Package filters provides query filters for specific operations. |
|
db/types
Package types provides some shared database types.
|
Package types provides some shared database types. |
|
email
Package email provides functions to send emails.
|
Package email provides functions to send emails. |
|
metrics
Package metrics provides a prometheus/open-metrics route.
|
Package metrics provides a prometheus/open-metrics route. |
|
opds
Package opds provides the routes for the OPDS catalogs.
|
Package opds provides the routes for the OPDS catalogs. |
|
opds/catalog
Package catalog provides type to create an OPDS catalog of entries.
|
Package catalog provides type to create an OPDS catalog of entries. |
|
profile
Package profile provides the user's profile management routes.
|
Package profile provides the user's profile management routes. |
|
profile/preferences
Package preferences provides a struct with methods to get some user preferences values.
|
Package preferences provides a struct with methods to get some user preferences values. |
|
searchstring
Package searchstring provides a search string parser.
|
Package searchstring provides a search string parser. |
|
server
Package server is the main Readeck HTTP server.
|
Package server is the main Readeck HTTP server. |
|
sessions
Package sessions provides a cookie based session manager.
|
Package sessions provides a cookie based session manager. |
|
testing
Package testing provides tools to tests the HTTP routes, the message bus, email sending, etc.
|
Package testing provides tools to tests the HTTP routes, the message bus, email sending, etc. |
|
videoplayer
Package videoplayer provides a route for an HLS embed video player.
|
Package videoplayer provides a route for an HLS embed video player. |
|
Package locales provides l10n tools to render gettext text.
|
Package locales provides l10n tools to render gettext text. |
|
pkg
|
|
|
accept
Package accept provides a parser for HTTP Accept* headers.
|
Package accept provides a parser for HTTP Accept* headers. |
|
annotate
Package annotate provides an annotation framework for HTML content.
|
Package annotate provides an annotation framework for HTML content. |
|
archiver
Package archiver provides functions to archive the content of a full HTML page.
|
Package archiver provides functions to archive the content of a full HTML page. |
|
bleach
Package bleach is a simple HTML sanitizer tool.
|
Package bleach is a simple HTML sanitizer tool. |
|
csp
Package csp provides simple tools to create and modify a Content Security Policy.
|
Package csp provides simple tools to create and modify a Content Security Policy. |
|
epub
Package epub creates EPUB files.
|
Package epub creates EPUB files. |
|
extract
Package extract is a content extractor for HTML pages.
|
Package extract is a content extractor for HTML pages. |
|
extract/contents
Package contents provide extraction processes for content processing (readability) and plain text conversion.
|
Package contents provide extraction processes for content processing (readability) and plain text conversion. |
|
extract/contentscripts
Package contentscripts provides a JavaScript engine that runs builtin, or user defined, scripts during the extraction process.
|
Package contentscripts provides a JavaScript engine that runs builtin, or user defined, scripts during the extraction process. |
|
extract/meta
Package meta provides extract processors to retrieve several meta information from a page (meta tags, favicon, pictures...).
|
Package meta provides extract processors to retrieve several meta information from a page (meta tags, favicon, pictures...). |
|
extract/srcset
Package srcset is an srcset value parser.
|
Package srcset is an srcset value parser. |
|
forms
Package forms provides helpers and functions to create and validate forms.
|
Package forms provides helpers and functions to create and validate forms. |
|
glob
Package glob provides a function to test glob strings.
|
Package glob provides a function to test glob strings. |
|
img
Package img provides a unified image loader and manipulation pipeline.
|
Package img provides a unified image loader and manipulation pipeline. |
|
img/ico
Package ico implements the .ico format decoding
|
Package ico implements the .ico format decoding |
|
libjet
Package libjet provides some utility functions for Jet templates.
|
Package libjet provides some utility functions for Jet templates. |
|
opds
Package opds provides types and functions to create OPDS content.
|
Package opds provides types and functions to create OPDS content. |
|
strftime
Package strftime provides an strftime() implementation for Time formating.
|
Package strftime provides an strftime() implementation for Time formating. |
|
superbus
Package superbus provides an asynchronous task handler.
|
Package superbus provides an asynchronous task handler. |
|
timetoken
Package timetoken is a simple utility to convert a text into a time value.
|
Package timetoken is a simple utility to convert a text into a time value. |
|
utils
Package utils provides simple various utilities
|
Package utils provides simple various utilities |
|
xml2map
Package xml2map provides an XML decoder returning a map of properties parsed from a given XML input.
|
Package xml2map provides an XML decoder returning a map of properties parsed from a given XML input. |
|
zipfs
Package zipfs provides tools to serve content directly from a zip file to an HTTP response.
|
Package zipfs provides tools to serve content directly from a zip file to an HTTP response. |
|
tools
|
|
|
docs
tools/docs is a script that builds an HTML documentation based on markdown files in a source directory.
|
tools/docs is a script that builds an HTML documentation based on markdown files in a source directory. |
|
ftr
tools/ftr provides a command line interface to convert site config text files to JSON files.
|
tools/ftr provides a command line interface to convert site config text files to JSON files. |