Updated README

feat/db
Antonio De Lucreziis 2 years ago
parent 0f7bde6232
commit c9d02d22dd

@ -1,77 +1,122 @@
# 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
# 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 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`
- `github.com/litao91/goldmark-mathjax`
Library used to load `.env` config files.
- `github.com/yuin/goldmark`
- `github.com/yuin/goldmark-highlighting`
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`
- **NodeJS**
Used to load YAML frontmatter in Markdown documents.
- AlpineJS
- `github.com/alecthomas/repr`
- FuseJS
Utility to pretty print Go values.
## Setup
### Architecture
Per ottenere il progetto basta fare
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.
```bash
$ git clone https://git.phc.dm.unipi.it/phc/website
$ cd frontend/
frontend/ $ npm install
frontend/ $ cd ..
$ make frontend
```
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.
## Development
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.
### Setup
The `model/` package provides some common types used in the whole application.
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.
The `config/` package is just a singleton loaded when the application is started providing config values loaded from a `.env` file.
```bash shell
$ cp .env.dev .env
$ go run .
```
#### Services
### Server
All other Go packages are services used by the `handler/` packages that provide authentication (`auth/`), template rendering (`templates/`), articles loading (`articles/`).
Un comando comodo in fase di development che usa [`entr`](https://github.com/eradman/entr) è
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).
```bash shell
$ find . -type f -name '*.go' | entr -r go run .
# O anche con fd...
$ fd -e go | entr -r go run .
## 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>
...
```
### Frontend
- `profilo.js`
Se si sta anche modificando codice dentro `frontend/`, in contemporanea serve anche fare
Script che aggiunge un minimo di interattività alla pagina renderizzata da `_views/profilo.html`
```bash shell
$ make frontend
# O anche con un watcher...
$ fd -e js | entr make frontend
```html
<script src="https://unpkg.com/alpinejs@3.x.x/dist/cdn.min.js"></script>
<script src="/public/profilo.min.js"></script>
```
### Environment Variables
## Environment Variables
- `MODE`
@ -79,21 +124,33 @@ $ fd -e js | entr make frontend
- `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`
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…
Cancel
Save