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

# 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 when go files change
$ printf '%s\n' $(echo **/*.go) | entr -r go run ./cmd/phc-website-server

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

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.

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

• 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