Introduction

This is my blog, built for my own needs.

Features

• Non-authenticated users are only able to:
  • Read the published articles.
  • Read the articles from a bunch of RSS feeds I find useful, mostly programming related.
• Authenticated users are also able to:
  • Manage articles (publish, edit and delete).
  • Manage the followed RSS feeds.
  • Force the reload of the RSS feeds cache.

The blog articles support Markdown and code syntax highlighting.

NOTE: to correctly display the RSS articles, HTML sanitization is bypassed (only for this case), so that <iframe> elements are displayed as intended.
This means that only trusted RSS feeds should be followed, as no HTML sanitization means XSS!

RSS feeds caching

The articles fetched from the followed RSS feeds are cached for a few hours to drastically improve loading times and to reduce the server's workload... bandwidth ain't free.

Compiling from source

Using Docker

Recommended for production.

Requirements

• Docker
• Docker Compose

Steps

1. Generate SSL certificates for HTTPS and save the files inside a secure location on your server.

   You can use Cloudflare origin CA to generate the files origin.pem and private.pem.

2. Navigate to the repository root, copy the file .env.example, rename it to .env, then set your sensitive data.

3. Generate the private and public keys used to create the login tokens. Please refer to backend/src/main/resources/certs/README.md for instructions.

4. Run the application:

   docker compose up -d --build

5. Change the password (along the other details) of the default user:

   docker exec -it tino-blog-db bash
   psql -d tino_blog -U postgres

   Enter your password, then execute the update statement:

   UPDATE users
   SET username = 'your_username',
       email = 'your@email.org',
       password = 'your_super_secret_bcrypt_encrypted_password'
   WHERE id = '4c7dbc23-b524-4dd2-95f0-c0cb974588c7';
   

6. Open the webapp: https://localhost

Manual native setup (for local development only!)

Requirements

• Java 21
• PostgreSQL 17 (15 and 16 are also both fine as well)
• Angular CLI

Steps

Remember that after modifying the files *.properties, it may be necessary to run:

mvn clean package

1. Configure the Spring "active profile" to dev, so that application-dev.properties is used over application.properties: this allows Spring to generate the database tables and to use default certificates for user authentication.

2. The database must be created manually using PostgreSQL: the default name is "tino_blog", but it can be customized using environment variables (see point number 3): the tables will be created by Spring during the first run.

3. To initialize the database with default data (first user and a bunch of RSS feeds), you can run this:

   psql -U postgres -d tino_blog -f backend/src/main/resources/data.sql
   

   Credentials of the first admin user, created during data initialization:
   Email: admin@test.org
   Password: password

4. Configure the following environment variables for the backend (it can be done using IntelliJ IDEA "run configuration" or via system, for example, by running export MY_ENV_VAR=123 on Linux and macOS):

   • DB_HOST (default "localhost")
   • DB_PORT (default "5432")
   • DB_NAME (default "tino_blog")
   • DB_USER
   • DB_PASSWORD

5. Navigate to the backend directory and compile it:

   mvn clean package

6. Run the backend:

   java -jar target/tino-blog-1.2.0.war

7. Navigate to the frontend directory and run it:

   npm install
   ng serve

8. Open the webapp: http://localhost:4200

---

Contributing

In case of database changes

If the database schema changes, the DDL instructions must be exported into the file backend/src/main/resources/schema.sql, which is used when building the Docker image for the database.
This can be done with:

pg_dump -U db_username tino_blog >> schema.sql

Then, remove all the instructions like:

ALTER TABLE public.articles
    OWNER TO postgres;

otherwise it won't be possible to specify custom database users in the .env file.

By removing the explicit tables' ownership to a specific user, ownership will default to the user creating them, allowing for easier customization of the database username to improve security.

Migration scripts

Scripts to migrate the database must be created inside backend/src/main/resources/sql-updates to keep compatibility with existing builds.
Migration scripts must be executed manually when updating from an older version.

Customize Bootstrap theme

Some Bootstrap colors were changed in the file frontend/src/custom_bootstrap/custom.scss.
If the SASS changes, it needs to be compiled again in CSS:

1. Install SASS:

   npm install -g sass

2. Compile the .scss file to .css:

   sass --watch frontend/src/custom_bootstrap/custom.scss frontend/src/custom_bootstrap/custom.css

The full reference can be found here.

---

Colors...

Yes, I did steal some colors from the color palette of GitHub, as it's perfect, and I'm no good designer.