Updated README
This commit is contained in:
@@ -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
|
||||||
- `github.com/alecthomas/repr`
|
|
||||||
|
|
||||||
- `github.com/go-chi/chi/v5`
|
|
||||||
|
|
||||||
- `github.com/joho/godotenv`
|
|
||||||
|
|
||||||
- `github.com/litao91/goldmark-mathjax`
|
|
||||||
|
|
||||||
- `github.com/yuin/goldmark`
|
|
||||||
|
|
||||||
- `github.com/yuin/goldmark-highlighting`
|
|
||||||
|
|
||||||
- `gopkg.in/yaml.v3`
|
|
||||||
|
|
||||||
- **NodeJS**
|
|
||||||
|
|
||||||
- AlpineJS
|
|
||||||
|
|
||||||
- FuseJS
|
|
||||||
|
|
||||||
## Setup
|
|
||||||
|
|
||||||
Per ottenere il progetto basta fare
|
|
||||||
|
|
||||||
```bash
|
|
||||||
$ git clone https://git.phc.dm.unipi.it/phc/website
|
$ git clone https://git.phc.dm.unipi.it/phc/website
|
||||||
$ cd frontend/
|
$ cd _frontend
|
||||||
frontend/ $ npm install
|
$ make setup
|
||||||
frontend/ $ cd ..
|
|
||||||
$ make frontend
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## Development
|
To just do a full build and start the project run
|
||||||
|
|
||||||
### Setup
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
```bash shell
|
```bash shell
|
||||||
|
# Setup local development env file
|
||||||
$ cp .env.dev .env
|
$ cp .env.dev .env
|
||||||
$ go run .
|
|
||||||
|
# Do a full build of frontend and backend
|
||||||
|
$ make all
|
||||||
|
|
||||||
|
# Compile and start the server
|
||||||
|
$ go run -v ./cmd/phc-website-server
|
||||||
```
|
```
|
||||||
|
|
||||||
### Server
|
Alternativamente se si sta modificando in live il codice è comodo usare [`entr`](https://github.com/eradman/entr) e `fd` (un'alternativa a `find`)
|
||||||
|
|
||||||
Un comando comodo in fase di development che usa [`entr`](https://github.com/eradman/entr) è
|
|
||||||
|
|
||||||
```bash shell
|
```bash shell
|
||||||
$ find . -type f -name '*.go' | entr -r go run .
|
# Restart when go files change
|
||||||
# O anche con fd...
|
$ printf '%s\n' $(echo **/*.go) | entr -r go run ./cmd/phc-website-server
|
||||||
$ fd -e go | entr -r go run .
|
|
||||||
|
# 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
|
||||||
```
|
```
|
||||||
|
|
||||||
### Frontend
|
## Backend
|
||||||
|
|
||||||
Se si sta anche modificando codice dentro `frontend/`, in contemporanea serve anche fare
|
### Dependencies
|
||||||
|
|
||||||
```bash shell
|
- `github.com/gofiber/fiber/v2`
|
||||||
$ make frontend
|
|
||||||
# O anche con un watcher...
|
|
||||||
$ fd -e js | entr make frontend
|
|
||||||
```
|
|
||||||
|
|
||||||
### Environment Variables
|
Backend server framework.
|
||||||
|
|
||||||
- `MODE`
|
- `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/`
|
||||||
|
|
||||||
|
- `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>
|
||||||
|
```
|
||||||
|
|
||||||
|
## Environment Variables
|
||||||
|
|
||||||
|
- `MODE`
|
||||||
|
|
||||||
Può essere `production` (default) o `development`.
|
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,
|
Indirizzo di posta elettronica per contattare gli amministratori del sito,
|
||||||
che compare nel footer di ogni pagina.
|
che compare nel footer di ogni pagina.
|
||||||
|
|
||||||
- `<SERVIZIO>_URL`
|
|
||||||
|
- `<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).
|
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
|
## 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/)
|
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/)
|
||||||
|
|||||||
Reference in New Issue
Block a user