website/README.md

# phc/website

Backend e frontend del nuovo sito per il PHC.

## Usage

To setup the project

```bash shell
# 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

```bash shell
# 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`](https://github.com/eradman/entr) e `fd` (un'alternativa a `find`)

```bash shell
# 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

```bash shell
# 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

    ```html
    ...
    <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`

    ```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.

    ```html
    <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:8080`.

- `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](https://git.phc.dm.unipi.it/phc/auth-service/)