Skip to content
Klutch.sh Docs

Deploying Precis

Introduction

Precis is a self-hosted news aggregator designed to help you stay informed by collecting and organizing content from various RSS and Atom feeds in one central location. Unlike commercial news aggregators, Precis gives you complete control over your reading experience without tracking, ads, or algorithmic manipulation.

Built with simplicity in mind, Precis provides a clean, distraction-free reading interface that focuses on content rather than engagement metrics. It supports multiple users, feed categorization, and various display options to match your reading preferences.

Key highlights of Precis:

  • Feed Aggregation: Subscribe to RSS and Atom feeds from any source
  • Clean Interface: Distraction-free reading experience focused on content
  • Multi-User Support: Share your instance with family or team members
  • Feed Categories: Organize feeds into logical groups
  • Offline Reading: Save articles for later reading
  • Mobile Responsive: Read comfortably on any device
  • No Tracking: Complete privacy with no third-party analytics
  • Open Source: Full control over your news reading experience

This guide walks through deploying Precis on Klutch.sh using Docker.

Why Deploy Precis on Klutch.sh

Deploying Precis on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Precis without complex configuration.

Persistent Storage: Attach persistent volumes for your feed database and user data.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for secure access.

GitHub Integration: Connect your repository directly from GitHub for automatic deployments.

Custom Domains: Assign a custom domain for personalized access.

Always-On Availability: Your news aggregator remains accessible 24/7.

Prerequisites

Before deploying Precis on Klutch.sh, ensure you have:

  • A Klutch.sh account
  • A GitHub account with a repository for your Precis configuration
  • Basic familiarity with Docker and containerization concepts
  • A list of RSS/Atom feeds you want to follow
  • (Optional) A custom domain for your Precis instance

Preparing Your Repository

Create a GitHub repository containing your Dockerfile for Precis deployment.

Repository Structure

precis-deploy/
├── Dockerfile
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM python:3.11-slim


WORKDIR /app


# Install system dependencies
RUN apt-get update && apt-get install -y \
    gcc \
    libpq-dev \
    && rm -rf /var/lib/apt/lists/*


# Install Precis
RUN pip install --no-cache-dir precis-reader gunicorn


# Create data directory
RUN mkdir -p /app/data


# Set environment variables
ENV PRECIS_DATA_DIR=/app/data
ENV PRECIS_SECRET_KEY=${SECRET_KEY}


EXPOSE 8000


CMD ["gunicorn", "--bind", "0.0.0.0:8000", "--workers", "2", "precis:app"]

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store
__pycache__
*.pyc
.env

Deploying Precis on Klutch.sh

    Generate a Secret Key

    Generate a secure secret key for session management:

    Terminal window
    python -c "import secrets; print(secrets.token_hex(32))"

    Push Your Repository to GitHub

    Initialize your repository and push to GitHub:

    Terminal window
    git init
    git add Dockerfile .dockerignore
    git commit -m "Initial Precis deployment configuration"
    git remote add origin https://github.com/yourusername/precis-deploy.git
    git push -u origin main

    Create a New Project on Klutch.sh

    Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “precis” or “news-reader”.

    Create a New App

    Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your Precis Dockerfile.

    Configure HTTP Traffic

    In the deployment settings:

    • Select HTTP as the traffic type
    • Set the internal port to 8000

    Set Environment Variables

    Add the following environment variables:

    VariableValue
    SECRET_KEYYour generated secret key
    PRECIS_DATA_DIR/app/data

    Attach Persistent Volumes

    Add the following volumes:

    Mount PathRecommended SizePurpose
    /app/data5 GBDatabase and cached articles

    Deploy Your Application

    Click Deploy to start the build process. Klutch.sh will:

    • Detect your Dockerfile automatically
    • Build the container image
    • Attach the persistent volumes
    • Start the Precis container
    • Provision an HTTPS certificate

    Access Precis

    Once deployment completes, access your Precis instance at https://your-app-name.klutch.sh. Create your account and start adding feeds.

Using Precis

Adding Feeds

  1. Log in to your Precis instance
  2. Navigate to the feed management section
  3. Enter the RSS or Atom feed URL
  4. Assign a category (optional)
  5. Save the feed

Organizing Content

  • Create categories to group related feeds
  • Mark articles as read or save for later
  • Use keyboard shortcuts for efficient navigation
  • Filter by read/unread status

Consider subscribing to feeds from:

  • News organizations
  • Technology blogs
  • Industry publications
  • Personal blogs
  • Podcast feeds
  • YouTube channels (via RSS)

Troubleshooting Common Issues

Feeds Not Updating

Solutions:

  • Verify the feed URL is valid and accessible
  • Check for feed parsing errors in logs
  • Ensure the feed source is not rate limiting

Cannot Access Instance

Solutions:

  • Verify the deployment is running
  • Check that HTTP traffic is configured correctly
  • Clear browser cache and try again

Additional Resources

Conclusion

Deploying Precis on Klutch.sh gives you a clean, self-hosted news aggregator that respects your privacy and puts you in control of your reading experience. Without algorithms deciding what you see, you can focus on the content that matters most to you.