Jenselme / legadilo

Read your RSS feeds & save other articles
https://www.legadilo.eu
GNU Affero General Public License v3.0
0 stars 0 forks source link
agplv3 blogging django htmx python3 rss-aggregator rss-reader

Legadilo

Read your RSS feeds & save other articles

Built with Cookiecutter Django Black code style License: AGPL v3

Legadilo is a project to help you subscribe to RSS feeds, save articles and organize them easily with tags and full customizable reading lists! It’s written with the Django web framework, the boostrap 5 frontend toolkit and with enhancements given by htmx.

It’s opensource under the GNU AGPLv3 and is designed to be self-hostable, so you can run your own instance. Your ideas, contributions and feedback are welcomed! You can also check the official instance to start using it more easily (you will be able to export and import your data in any instance)! If you contribute, don’t forget to add yourselves to the CONTRIBUTORS.txt file.

Developing

Start the project locally

  1. Ensure you have Docker and node installed.
  2. Run npm install to install our few JS deps.
  3. Run docker compose -f local.yml up
  4. The site should be accessible at http://localhost:8000

Using VSCode

You can rely on the devcontainer.json file to start the project and develop teh project inside a container. This way, you don’t need to install anything on your machine to make it work (besides docker). VSCode should propose you continue in a container the first time you open the project and will take care of the rest for you. See here for more.

You will have to start Django with the provided run target.

Using Pycharm

By default, everything is set up to develop locally with Pycharm. So you will need docker (for the database), poetry, Python 3.12 and nodeJS 20+ installed for this to work. Django will be started automatically. On the first run, you must run npm install to install a few JS deps.

You should also be able to use devcontainers but the support is more recent and isn’t as good as in VSCode according to my tests. See here for more.

Project structure

Basic Commands

All these commands must be run at the root of the project!

Email Server

In development, it is often nice to be able to see emails that are being sent from your application. For that reason local SMTP server Mailpit with a web interface is available as docker container.

Container mailpit will start automatically when you will run all docker containers. Please check cookiecutter-django Docker documentation for more details how to start all containers.

With Mailpit running, to view messages that are sent by your application, open your browser and go to http://127.0.0.1:8025

Setting Up Your Users

For convenience, you can keep your normal user logged in on Chrome and your superuser logged in on Firefox (or similar), so that you can see how the site behaves for both kinds of users.

Writing code

All code should be tested and type annotated. We use pytest as our test runner and mypy as our type checker. We use ruff to lint and format our code. You can:

Commiting

To ease development, we use pre-commit to run all our linters before each commit.

We try to follow the same rules as the angular project towards commits. Each commit is constituted from a summary line, a body and eventually a footer. Each part are separated with a blank line.

The summary line is as follows: <type>(<scope>): <short description>. It must not end with a dot and must be written in present imperative. Don't capitalize the fist letter. The whole line shouldn't be longer than 80 characters and if possible be between 70 and 75 characters. This is intended to have better logs.

The possible types are:

The body should be written in imperative. It can contain multiple paragraph. Feel free to use bullet points.

Use the footer to reference issue, pull requests or other commits.

This is a full example:

feat(css): use CSS sprites to speed page loading

- Generate sprites with the gulp-sprite-generator plugin.
- Add a build-sprites task in gulpfile

Close #24

Browse the project history to see how contributors last did it in the past!

Create a new app

Apps are useful to structure the project. To create a new one, use the commands below:

APP_NAME=<APP_NAME>
mkdir legadilo/$APP_NAME
django-admin startapp --template .app-template $APP_NAME legadilo/$APP_NAME

Don’t forget to add it to INSTALLED_APPS!

Deployment

See this page.