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 better 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 guarantees 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 at:
http://localhost:8000/
Installation from source code
Installing from source can be useful to try out unreleased Readeck versions, or to set up a development environment for contributing code. For more information, see the development documentation.
Installation for production
If you already know how to deploy containers on a server, installing Readeck for production should be quite straightforward. As for deploying to Linux servers with systemd and NGINX reverse proxy, see the deployment guide.
FAQ
Please refer to the FAQ on readeck.org.
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.
Contributing
Readeck's simple stack means that the barrier to entry is relatively low when it comes to contributing to the Readeck project. Contributions are welcome by filing issues, participating in community discussions, submitting translations, and proposing changes to the source code. For more information, see the documentation on contributing.
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 provides the RBAC policy for Readeck.
|
Package acls provides the RBAC policy for Readeck. |
|
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/oauth2
Package oauth2 provides the routes to authorize a client and retrieve an API token.
|
Package oauth2 provides the routes to authorize a client and retrieve an API token. |
|
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/converter
Package converter provides bookmark export/converter tooling.
|
Package converter provides bookmark export/converter tooling. |
|
bookmarks/dataset
Package dataset contains the basic blocks to properly render bookmarks related items.
|
Package dataset contains the basic blocks to properly render bookmarks related items. |
|
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/exp
Package exp provides query expressions for specific operations.
|
Package exp provides query expressions for specific operations. |
|
db/migrations
Package migrations provides database migrations as SQL files and compiled functions.
|
Package migrations provides database migrations as SQL files and compiled functions. |
|
db/scanner
Package scanner provides tools for scanning goqu results.
|
Package scanner provides tools for scanning goqu results. |
|
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. |
|
httpclient
Package httpclient is Readeck's own HTTP client.
|
Package httpclient is Readeck's own HTTP client. |
|
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. |
|
portability
Package portability handles data export and import.
|
Package portability handles data export and import. |
|
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. |
|
server/urls
Package urls provides functions to work with the server URLs.
|
Package urls provides functions to work with the server URLs. |
|
sessions
Package sessions provides a cookie based session manager.
|
Package sessions provides a cookie based session manager. |
|
templates
Package templates provides the Jet template loader and catalog.
|
Package templates provides the Jet template loader and catalog. |
|
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
|
|
|
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 a full HTML page with its assets.
|
Package archiver provides functions to archive a full HTML page with its assets. |
|
atom
Package atom provides an Atom feed generator.
|
Package atom provides an Atom feed generator. |
|
base58
Package base58 implements base58 encoding
|
Package base58 implements base58 encoding |
|
bleach
Package bleach is a simple HTML sanitizer tool.
|
Package bleach is a simple HTML sanitizer tool. |
|
csvstruct
Package csvstruct allows scanning of string slice obtained from a csv.Reader.Read call into a struct type.
|
Package csvstruct allows scanning of string slice obtained from a csv.Reader.Read call into a struct type. |
|
ctxr
Package ctxr provides generic functions to work with context storage.
|
Package ctxr provides generic functions to work with context storage. |
|
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/meta/tinymeta
Package tinymeta implements reading metadata from HTML documents without having to parse the entire DOM in memory.
|
Package tinymeta implements reading metadata from HTML documents without having to parse the entire DOM in memory. |
|
extract/microdata
Package microdata provides a JSON-LD and HTML microdata parser and resolver.
|
Package microdata provides a JSON-LD and HTML microdata parser and resolver. |
|
extract/srcset
Package srcset is an srcset value parser.
|
Package srcset is an srcset value parser. |
|
extract/testing
Package testing provides some tools for fixture loading as HTTP mock responses.
|
Package testing provides some tools for fixture loading as HTTP mock responses. |
|
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. |
|
http/accept
Package accept provides a parser for HTTP Accept* headers.
|
Package accept provides a parser for HTTP Accept* headers. |
|
http/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. |
|
http/forwarded
Package forwarded provides tools to deal with proxy related HTTP Headers.
|
Package forwarded provides tools to deal with proxy related HTTP Headers. |
|
http/linkheader
Package linkheader is a parser for "Link" HTTP header values.
|
Package linkheader is a parser for "Link" HTTP header values. |
|
http/permissionspolicy
Package permissionspolicy provides simple tools to create and modify a Permissions Policy.
|
Package permissionspolicy provides simple tools to create and modify a Permissions Policy. |
|
http/request
Package request provides two middlewares that will set the request's URL based on a fixed address and/or reverse proxy headers.
|
Package request provides two middlewares that will set the request's URL based on a fixed address and/or reverse proxy headers. |
|
http/securecookie
Package securecookie provides a cookie handler that encrypts its payload.
|
Package securecookie provides a cookie handler that encrypts its payload. |
|
img
Package img provides a unified image loader and manipulation pipeline.
|
Package img provides a unified image loader and manipulation pipeline. |
|
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. |
|
totp
Package totp provides the building block the generate and check a TOTP key.
|
Package totp provides the building block the generate and check a TOTP key. |
|
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
command
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
command
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. |
|
yaml-compose
command
package main contains the yaml-compose code.
|
package main contains the yaml-compose code. |