Updated README
parent
0f7bde6232
commit
c9d02d22dd
@ -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 <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`.
|
||||
|
||||
- `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.
|
||||
|
||||
- `<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).
|
||||
|
||||
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/)
|
||||
|
||||
Loading…
Reference in New Issue