tailucas/pocket-lint

Telegram bot that fetches links from https://getpocket.com/

About The Project

This Docker application runs a Python Telegram Bot instance that offers management of items in a user's Pocket account. This application extends my own boilerplate application hosted in docker hub and takes its own git submodule dependency on my own package. This documentation covers the bot Python project; for user documentation see my github page for this project.

Basic features of this bot application:

• This Docker application inherits all runtime features discussed in the base application.
• Configures, enables and tracks a free-tier ngrok tunnel to receive OAuth call-backs from Pocket during the authentication workflow.
• Stores authentication tokens, encrypted at rest, in a local SQLite database and supports backups to AWS S3.
• Offers various bot commands to the user, and persists pick positions using digests if referencing user tags.
• Conforms with Telegram's v20 API which uses the Python asyncio paradigm to manage inherently asynchronous bot user activities. Due to this, the project also takes advantage of SQLAlchemy asyncio bindings to their SQLite interface.

What user content is stored?

This is one of the most important reasons to open-source such a project. As far as possible, the absolute minimum information is stored in a local database with the bot. Under INFO level logging, no user-specific information is logged to the application logs other than tracking essential bot activity. Authentication tokens that allow the bot to interact with the Pocket APIs need to be persisted by the bot and are encrypted at rest using the AES cipher in GCM mode. User preferences are keyed using the Telegram user ID and pick positions that include tags stored as SHA384 digests.

• Database models
• Crypto implementation

(back to top)

Built With

Technologies that help make this package useful:

Also:

• Cronitor
• Healthchecks
• Starlette
• SQLAlchemy
• Uvicorn

(back to top)

Getting Started

Here is some detail about the intended use of this package.

Prerequisites

Beyond the Python dependencies defined in the Poetry configuration, the package init carries hardcoded dependencies on Sentry and 1Password in order to function. Unless you want these and are effectively extending my base project, you're likely better off forking this package and cutting out what you do not need.

Installation

0. 🛑 This project uses 1Password Secrets Automation to store both application key-value pairs as well as runtime secrets. It is assumed that the connect server containers are already running on your environment. If you do not want to use this, then you'll need to fork this package and make the changes as appropriate. It's actually very easy to set up, but note that 1Password is a paid product with a free-tier for secrets automation. Here is an example of how this looks for my application and the generation of the docker-compose.yml relies on this step. Your secrets automation vault must contain an entry called ENV.pocket_lint with these keys:

• DEVICE_NAME: For naming the container. This project uses pocket-lint.
• APP_NAME: Used for referencing the application's actual name for the logger. This project uses pocket_lint.
• OP_CONNECT_SERVER, OP_CONNECT_TOKEN, OP_CONNECT_VAULT: Used to specify the URL of the 1Password connect server with associated client token and Vault ID. See 1Password for more.
• AWS_CONFIG_FILE: Standard local location of the AWS configuration file. This project uses /home/app/.aws/config.
• HC_PING_URL: Healthchecks URL of this application's current health check status.
• CRONITOR_MONITOR_KEY: Token to enable additional health checks presented in Cronitor. This tracks thread count and overall health.
• AWS_DEFAULT_REGION: Used by AWS tools like S3 backup location.
• NGROK_ENABLED: Enables download and configuration of ngrok client.
• TABLESPACE_PATH: The location of the physical SQLite tablespace created by the application. This project uses /data/pocket_lint.db.
• INFLUXDB_BUCKET: The configured bucket in InfluxDB that records some application telemetry.
• TELEGRAM_BOT_LINK: The link to Telegram's short URL. This project uses http://t.me/PocketLintBot.
• HELP_URL: Used to specify the location of the user help. This project uses https://tailucas.github.io/pocket-lint/.

With these configured, you are now able to build the application.

In addition to this, additional runtime configuration is used by the application, and also need to be contained within the secrets vault. With these configured, you are now able to run the application.

1. Clone the repo

   git clone https://github.com/tailucas/pocket-lint.git

2. Verify that the git submodule is present.

   git submodule init
   git submodule update

3. Make the Docker runtime user and set directory permissions. ✋ Be sure to first review the Makefile contents for assumptions around user IDs for Docker.

   make user

4. Now generate the docker-compose.yml:

   make setup

5. And generate the Docker image:

   make build

6. If successful and the local environment is running the 1Password connect containers, run the application. For foreground:

   make run

   For background:

   make rund

(back to top)

Usage

Assuming that you've already configured a Telegram bot, running this application will bring the bot to life.

(back to top)

License

Distributed under the MIT License. See LICENSE for more information.

(back to top)

Acknowledgments

• PyCryptodome
• Pocket client for Python
• Template on which this README is based
• All the Shields

(back to top)