diff --git a/README.md b/README.md index 867bcc6..a75df79 100644 --- a/README.md +++ b/README.md @@ -1,99 +1,156 @@ -# Nuovo Sito PHC +# phc/website -Repo del server del nuovo sito per il PHC. +Backend e frontend del nuovo sito per il PHC. -## Dipendenze +## Usage -- **Golang** +To setup the project - - `github.com/alecthomas/chroma` +```bash shell +# Clone the repo +$ git clone https://git.phc.dm.unipi.it/phc/website +$ cd _frontend +$ make setup +``` - - `github.com/alecthomas/repr` +To just do a full build and start the project run - - `github.com/go-chi/chi/v5` +```bash shell +# Setup local development env file +$ cp .env.dev .env - - `github.com/joho/godotenv` +# Do a full build of frontend and backend +$ make all - - `github.com/litao91/goldmark-mathjax` +# Compile and start the server +$ go run -v ./cmd/phc-website-server +``` - - `github.com/yuin/goldmark` +Alternativamente se si sta modificando in live il codice è comodo usare [`entr`](https://github.com/eradman/entr) e `fd` (un'alternativa a `find`) - - `github.com/yuin/goldmark-highlighting` +```bash shell +# Restart when go files change +$ printf '%s\n' $(echo **/*.go) | entr -r go run ./cmd/phc-website-server - - `gopkg.in/yaml.v3` +# 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 +``` -- **NodeJS** +## Backend - - AlpineJS +### Dependencies - - FuseJS +- `github.com/gofiber/fiber/v2` -## Setup + Backend server framework. -Per ottenere il progetto basta fare +- `github.com/joho/godotenv` -```bash -$ git clone https://git.phc.dm.unipi.it/phc/website -$ cd frontend/ -frontend/ $ npm install -frontend/ $ cd .. -$ make frontend -``` + Library used to load `.env` config files. -## Development +- `github.com/yuin/goldmark` -### Setup + 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. -Copiare il file `.env.dev` in `.env` per dire al server di lavorare in modalità di development e su quale indirizzo servire il sito, poi avviare il server. +- `gopkg.in/yaml.v3` -```bash shell -$ cp .env.dev .env -$ go run . -``` + Used to load YAML frontmatter in Markdown documents. -### Server +- `github.com/alecthomas/repr` -Un comando comodo in fase di development che usa [`entr`](https://github.com/eradman/entr) è + Utility to pretty print Go values. -```bash shell -$ find . -type f -name '*.go' | entr -r go run . -# O anche con fd... -$ fd -e go | entr -r go run . -``` +### Architecture -### Frontend +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. -Se si sta anche modificando codice dentro `frontend/`, in contemporanea serve anche fare +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. -```bash shell -$ make frontend -# O anche con un watcher... -$ fd -e js | entr make frontend -``` +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/`). -### Environment Variables +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). -- `MODE` +## 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 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/` + +- `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 + ... + + + + ... + ``` + +- `profilo.js` + + Script che aggiunge un minimo di interattività alla pagina renderizzata da `_views/profilo.html` + + ```html + + + ``` + +## Environment Variables + +- `MODE` Può essere `production` (default) o `development`. -- `HOST` +- `HOST` - Indirizzo (locale) sul quale servire il sito, di default è `localhost:8000`. + Indirizzo sul quale servire il sito, di default è `localhost:8000`. -- `MAIL` +- `EMAIL` Indirizzo di posta elettronica per contattare gli amministratori del sito, che compare nel footer di ogni pagina. -- `_URL` + +- `_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 `GIT_URL`, `CHAT_URL` e `USER_PAGES_BASE_URL`. + 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 servizio dipende dal servizio di autenticazione per permettere agli utenti di autenticarsi usando vari meccanismi. +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/)