From 19938091fa689df75babe0a5a3c06332bad28114 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Joakim=20Hells=C3=A9n?= Date: Tue, 13 Feb 2024 07:05:15 +0100 Subject: [PATCH] Improve documentation --- .env.example | 11 +++++++++++ .vscode/settings.json | 13 +++++++++++-- CONTRIBUTING.md | 43 +++++++++++++++++++++++++++++++++++++++++++ Docker.md | 31 +++++++++++++++++++++++++++++++ README.md | 11 ++++++++--- SECURITY.md | 11 +++++++++++ docker-compose.yml | 14 ++++++++++++++ 7 files changed, 129 insertions(+), 5 deletions(-) create mode 100644 .env.example create mode 100644 CONTRIBUTING.md create mode 100644 Docker.md create mode 100644 SECURITY.md create mode 100644 docker-compose.yml diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..538a593 --- /dev/null +++ b/.env.example @@ -0,0 +1,11 @@ + +PORT=8000 +DATABASE_URL=sqlite:///db.sqlite3 +ADMIN_EMAIL= +EMAIL_HOST_USER= +EMAIL_HOST_PASSWORD= +EMAIL_HOST=gmail.com +EMAIL_PORT=587 +DISCORD_WEBHOOK_URL= +APP_ENV=development +USER_AGENT=Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:124.0) Gecko/20100101 Firefox/124.0 diff --git a/.vscode/settings.json b/.vscode/settings.json index a8a7e21..0c0545a 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -51,6 +51,7 @@ "PGPORT", "PGUSER", "Prés", + "psql", "Rawr", "regexes", "Retour", @@ -59,6 +60,8 @@ "Scotty", "snek", "speedport", + "sqlc", + "sslmode", "steamloopback", "stretchr", "stylesheet", @@ -74,6 +77,12 @@ "Veni", "vidi", "webmail", - "XOXO" - ] + "XOXO", + "zerolog" + ], + "terminal.integrated.env.windows": { + "GOOSE_DRIVER": "postgres", + "GOOSE_DBSTRING": "user=feedvault password=feedvault dbname=feedvault sslmode=disable", + "GOOSE_MIGRATION_DIR": "${workspaceFolder}/sql/schema" + } } diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..0f81233 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,43 @@ +# Contributing to FeedVault + +Feel free to create a pull request for things like bug fixes, new features, and improvements. Your pull request doesn't have to be perfect, it just needs to work (or show what you're thinking). I can help you with the rest if needed. If you're not sure about something, feel free to open an issue first to discuss it. + +Please don't add any dependencies unless it's absolutely necessary. I want to try to keep the project using the standard library as much as possible. + +We use GitHub issues for tracking requests and bugs, so feel free to open an issue if you have any questions or need help. + +Thank you for your contributions! + +## Running the project + +You can run the project using the following command: + +```bash +go run cmd/feedvault/main.go +``` + +You can also run the tests using: + +```bash +go test ./... +``` + +## Using Docker + +We have a [Docker.md](Docker.md) file with instructions on how to run the project using Docker. + +## Using sqlc and goose + +I use [sqlc](https://docs.sqlc.dev/en/latest/index.html) for generating type safe Go from SQL. Make sure to regenerate the code after changing any SQL queries: + +```bash +sqlc generate +``` + +[goose](https://pressly.github.io/goose/) is used for managing database migrations. To create a new migration, run: + +```bash +goose create add_some_column sql +goose status +goose up +``` diff --git a/Docker.md b/Docker.md new file mode 100644 index 0000000..da89b51 --- /dev/null +++ b/Docker.md @@ -0,0 +1,31 @@ +# Docker Compose + +You can run the project using Docker Compose. You can use the following commands to build, run, and stop the project: + +```bash +docker compose build +docker compose up +docker compose down +``` + +## Accessing the database + +```bash +docker-compose exec db psql -U feedvault -d feedvault +``` + +## Environment variables + +You can use the following environment variables to configure the project: + +- `PORT`: The port to listen on (default: `8000`) +- `DATABASE_URL`: The URL of the database (default: `postgres://feedvault:feedvault@db/feedvault?sslmode=disable`) + - FeedVault only supports PostgreSQL at the moment +- `ADMIN_EMAIL`: The email where we should email errors to. +- `EMAIL_HOST_USER`: The email address to send emails from. +- `EMAIL_HOST_PASSWORD`: The password for the email address to send emails from. +- `EMAIL_HOST`: The SMTP server to send emails through. (default: `smtp.gmail.com`) +- `EMAIL_PORT`: The port to send emails through. (default: `587`) +- `DISCORD_WEBHOOK_URL`: The Discord webhook URL to send messages to. +- `APP_ENV`: The environment the app is running in. Development or Production. (default: `development`) +- `USER_AGENT`: The user agent to use for making requests. (default: `None`) diff --git a/README.md b/README.md index 0adebb7..febac91 100644 --- a/README.md +++ b/README.md @@ -8,12 +8,11 @@ FeedVault is an open-source web application written in Golang that allows users _Note: Some features are currently in development._ -- **Unified Feed Archiving**: Archive RSS, Atom, and JSON feeds seamlessly in one centralized location. +- **Unified Feed Archiving**: Archive RSS (0.90 to 2.0), Atom (0.3, 1.0), and JSON (1.0, 1.1) feeds seamlessly in one centralized location. - **Content Search**: Easily search your archive for specific content. - **Export Options**: Export your archive to various formats, including JSON, CSV, HTML, ODS, RST, TSV, XLS, XLSX, or YAML. - **API**: Access your archive programmatically through a API. - **Self-Hosting**: Host FeedVault on your own server for complete control over your data. -- **User-Friendly Design**: FeedVault is designed to be simple, intuitive, and responsive, working seamlessly on both desktop and mobile devices. - **Privacy-Focused**: FeedVault respects user privacy by not tracking or collecting any personal data. It is an ad-free platform that prioritizes user security. ## Usage @@ -23,9 +22,15 @@ _Note: Some features are currently in development._ - Add your favorite feeds to start archiving content. - Explore, manage, and enjoy your centralized feed archive. +## Docker + +Please see [Docker.md](Docker.md). + ## Contributing -We welcome contributions from the community! If you have ideas for new features, improvements, or bug fixes, feel free to open an issue or submit a pull request. +All contributions are welcome regardless of skill level or experience. + +Please read the [CONTRIBUTING.md](CONTRIBUTING.md) file for more information on how to contribute to FeedVault. ## Contact diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..f546617 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,11 @@ +# Reporting a Vulnerability + +tl;dr: [open a draft security advisory](https://github.com/TheLovinator1/FeedVault/security/advisories/new). + +--- + +You can also email me at [hello@feedvault.se](mailto:hello@feedvault.se). + +I am also available on Discord at `TheLovinator#9276`. + +Thanks :-) diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 0000000..3492647 --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,14 @@ +services: + db: + image: postgres:16 + container_name: feedvault-db + restart: unless-stopped + environment: + POSTGRES_USER: feedvault + POSTGRES_PASSWORD: feedvault # Change this to something more secure in production. + # .vscode/settings.json uses feedvault as the password for goose. https://github.com/pressly/goose + POSTGRES_DB: feedvault + volumes: + - ./data:/var/lib/postgresql/data + ports: + - "5432:5432"