website/README.md

phc/website

Backend e frontend del nuovo sito per il PHC.

Usage

To setup the project

# Clone the repo
$ git clone https://git.phc.dm.unipi.it/phc/website
$ cd _frontend
$ make setup

To just do a full build and start the project run

# Setup local development env file
$ cp .env.dev .env

# Setup and do a full build of frontend and backend
$ make all

# Compile and start the server
$ go run -v ./cmd/phc-website-server

Alternativamente se si sta modificando in live il codice è comodo usare entr e fd (un'alternativa a find)

# Restart server when go files change
$ printf '%s\n' $(echo **/*.go) | entr -r go run ./cmd/phc-website-server

Per ora non c'è ancora nessun sistema alternativo ma se si sta modificando codice della frontend in _frontend/ invece di riavviare ogni volta il server conviene lanciare in parallelo un watcher con

# Recompile files inside "_frontend/src" on change
_frontend/ $ pnpm run watch

Backend

Dependencies

• github.com/gofiber/fiber/v2

  Backend server framework.

• github.com/joho/godotenv

  Library used to load .env config files.

• github.com/yuin/goldmark

  Along with github.com/yuin/goldmark-highlighting, github.com/alecthomas/chroma and github.com/litao91/goldmark-mathjax are used to render Markdown articles and pages with latex expression and syntax highlighting.

• gopkg.in/yaml.v3

  Used to load YAML frontmatter in Markdown documents.

• github.com/alecthomas/repr

  Utility to pretty print Go values.

Architecture

The go project is organized as a library and the main server executable is inside cmd/phc-website-server that starts the server provided by the server/ package and injects all concrete service instances.

After a recent refactor all code that interacts with services is inside the handler/ package that abstracts away the HTTP server dependency to test more easily each route.

The handler/ has a Context type that for now is just used to pass around the user if the HTTP request contained a session token.

The model/ package provides some common types used in the whole application.

The config/ package is just a singleton loaded when the application is started providing config values loaded from a .env file.

Services

All other Go packages are services used by the handler/ packages that provide authentication (auth/), template rendering (templates/), articles loading (articles/).

Some very small services for now just have a single file and are storia.go and utenti.go (each provides a -Service interface and a default concrete implementation).

Frontend

Warning. Forse a breve ci sarà un lieve refactor da AlpineJS a Preact perché è più comodo.

All frontend code is stored inside the _frontend/ directory. (This will be implied in paths from now on)

This is a NodeJS project that uses https://pnpm.io/ as a package manager.

This project compiles javascript files using RollupJS (a tree shaking js bundler) and scss files using sass.

Javascript

These files a processed by RollupJS into out/

• base.js

  Script che avvia KaTeX e il theme switcher.

• utenti.js

  Script che si occupa di mostrare la lista degli utenti con fuzzy search.

  This script is imported by _views/utenti.html along side its dependencies loaded from common CDNs

  ...
  <script src="https://unpkg.com/alpinejs@3.x.x/dist/cdn.min.js"></script>
  <script src="https://cdn.jsdelivr.net/npm/fuse.js/dist/fuse.js"></script>
  <script src="/public/utenti.min.js"></script>
  ...
  

• profilo.js

  Script che aggiunge un minimo di interattività alla pagina renderizzata da _views/profilo.html

  <script src="https://unpkg.com/alpinejs@3.x.x/dist/cdn.min.js"></script>
  <script src="/public/profilo.min.js"></script>
  

• homepage-art.ts

  Script che renderizza l'animazione della homepage.

• appunti-condivisi.jsx

  Script che aggiunte l'interattività alla pagina /appunti/condivisi utilizzando Preact come libreria di UI.

  <script src="/public/appunti-condivisi.min.js"></script>
  

Environment Variables

• MODE

  Può essere production (default) o development.

• HOST

  Indirizzo sul quale servire il sito, di default è localhost:8000.

• EMAIL

  Indirizzo di posta elettronica per contattare gli amministratori del sito, che compare nel footer di ogni pagina.

• <SERVIZIO>_URL

  Rappresentano link ad altri servizi forniti, è comodo impostarli per testare tutto in locale su varie porte (e poi in produzione i vari url diventano link a sotto-domini del sito principale).

  Per ora ci sono solo i seguenti

  • GIT_URL
  • CHAT_URL

• BASE_URL

  Base dell'url per i link nel sito, per adesso usato per il feed RSS. In locale conviene impostarlo come HOST magari premettendo il protocollo (eg. http://localhost:8080)

• USER_PAGES_BASE_URL

  Base dell'url per le pagine utente di Poisson, di default https://poisson.phc.dm.unipi.it/~

• AUTH_SERVICE_HOST

  Indirizzo del servizio generico di autenticazione.

Altri Servizi

Questo progetto dipende dal servizio phc/auth-service che permettere agli utenti di autenticarsi usando vari meccanismi.

Il servizio di autenticazione di default girerà su localhost:3535 ed è documentato sulla repo auth-service