README.md 8.37 KB
Newer Older
Alexis POYEN's avatar
Alexis POYEN committed
1
2
# SDK - GO

Alexis POYEN's avatar
Alexis POYEN committed
3
4
[![Quality Gate Status](https://sonarqube.forge.grandlyon.com/api/project_badges/measure?project=sdk-go&metric=alert_status)](https://sonarqube.forge.grandlyon.com/dashboard?id=sdk-go) [![Security Rating](https://sonarqube.forge.grandlyon.com/api/project_badges/measure?project=sdk-go&metric=security_rating)](https://sonarqube.forge.grandlyon.com/dashboard?id=sdk-go) [![Technical Debt](https://sonarqube.forge.grandlyon.com/api/project_badges/measure?project=sdk-go&metric=sqale_index)](https://sonarqube.forge.grandlyon.com/dashboard?id=sdk-go) [![Vulnerabilities](https://sonarqube.forge.grandlyon.com/api/project_badges/measure?project=sdk-go&metric=vulnerabilities)](https://sonarqube.forge.grandlyon.com/dashboard?id=sdk-go)

Alexis POYEN's avatar
Alexis POYEN committed
5
6
7
8
9
10
11
12
13
14
15
16
17
18
Ce dépôt est un kit de développement en [GO](https://golang.org/) basé sur l'ORM [GORM](https://gorm.io/) qui permet facilement de créer et déployer des applications sous forme conteneurisée.

Le kit comprends une démonstration de ce qui peut être fait en simulant une application bancaire simplifiée développée en JavaScript et avec le framework CSS [Bulma](https://bulma.io/)

## Fonctionnalités

Les principales fonctionnalités :

- serveur d'API : basé sur le modèle de donnée définit dans l'ORM GORM
- serveur WEB : fournit à l'utilisateur l'application front-end (projet from scratch ou framework)
- authentification : permet à l'utilisateur de se connecter avec un compte local à l'application ou à partir d'un fournisseur d'identité OAuth2, de manière transparante
- gestion des droits : différents rôles peuvent être définit dans l'application et les API protégées par ces rôles
- gestion du cookie de session utilisateur chiffré entre le navigateur et le serveur

19
20
21
22
23
## Démarrage pour tests / dev

## Identifiants de démonstration

Trois comptes de démonstrations permettent de tester le kit avec trois profils différent : `admin` (rôle d'administrateur), `banker` (rôle de banquier), et `dupond` (rôle de client). Ces trois comptes ont pour mot de passe `password`
Alexis POYEN's avatar
Alexis POYEN committed
24
25

### Avec VS Code
26

Alexis POYEN's avatar
Alexis POYEN committed
27
28
29
30
> Il est nécessaire d'avoir un environnement de développement GO installé et opérationnel sur le poste.

Télécharger le dépot

Alexis POYEN's avatar
Alexis POYEN committed
31
```sh
Alexis POYEN's avatar
Alexis POYEN committed
32
33
34
35
36
git clone https://forge.grandlyon.com/apoyen/sdk-go.git
```

Ouvrir le dépôt avec VS Code puis dans l'onglet `Debug`, démarrer le projet avec `Debug SDK-GO with Mock OAuth2`

37
38
La démo est accessible avec l'url https://sdk-go.127.0.0.1.nip.io:1443

Alexis POYEN's avatar
Alexis POYEN committed
39
### Avec Docker
40

Alexis POYEN's avatar
Alexis POYEN committed
41
42
43
44
Installer sur le poste [Docker](https://docs.docker.com/get-docker/) et [docker-compose](https://docs.docker.com/compose/install/)

Télécharger le dépot

Alexis POYEN's avatar
Alexis POYEN committed
45
```sh
Alexis POYEN's avatar
Alexis POYEN committed
46
47
48
49
50
51
52
53
54
55
git clone https://forge.grandlyon.com/apoyen/sdk-go.git
cd sdk-go
```

Dans le fichier docker-compose.yml décommenter la ligne `command: -debug` (ATTENTION : cette ligne doit être commentée lors d'un passage en prod et ne sert que pour tester ou débuger l'application)

```sh
docker-compose up -d
```

56
57
La démo est accessible avec l'url https://sdk-go.127.0.0.1.nip.io

Alexis POYEN's avatar
Alexis POYEN committed
58
59
## Architecture

60
61
### Arborescence fichier

Alexis POYEN's avatar
Alexis POYEN committed
62
63
64
65
66
67
68
69
70
71
72
- `./data` contient les bases de données locales sqlite, users.db pour les utilisateurs et test.db pour le modèle de donnée
- `./dev-certificates` contient les fichiers nécessaires pour servir l'application en HTTPS durant le développement.
- `./internal` contient les paquets nécessaires au développement de l'application
    - `./auth` contient la gestion des utilisateurs et des droits sur l'application
    - `./mocks` permet de mocker l'API d'authentification pour passer les tests
    - `./models` permet de définri le modèle de données et les API qui seront servies par le back-end
    - `./rootmux` contient le fichier `rootmux.go` qui permet de servir les APIs, de gérer l'authentification, de servir le site web et la gestion des cookies utilisateurs. Le répertoire contient également tous les tests d'intégration sur les APIs.
- `./miscellaneous/keycloack` contient un environnement Keycloack qui peut être utilisé pour déployer un environnement OAuth2
- `./pkg` contient les diffférents package génériques qui permettent de gérer les logs applicatifs, de créer les fonctiones de tests, la gestion des tokens...
- `./web` est le répertoire où est stockée l'application front-end et publié par le serveur back-end.

73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
### Utilisateurs et droits

### Tests

## Démarer un projet à partir du SDK

Il faut forker le dépôt SDK-GO

### Nettoyage des fichiers

Supprimer le répertoire pkg. Ceci permet d'utiliser les dépendances `pkg` du dépôt SDK-GO directement et de bénéficier des mises à jour apportée sur ces packages.

Supprimer les fichiers `admin_test.go`, `banker_test.go` et `client_test.go` qui sont spécifiques à l'application de démonstration. Toutefois ces tests peuvent être adaptés à votre application pour tester les droits d'accès en fonction des rôles des utilisateurs.

Si vous souhaitez partir de l'interface web du kit, supprimer simplement les répertoires `web/components/bankerPage` et `web/components/clientPage` qui sont spécifiques à la démo.  
Sinon supprimer tout le contenu tout le contenu du répertoire `web` pour repartir de zéro, il faudra alors redévelopper l'interface de gestion des utilisateurs.

### Nommage de l'application

> ATTENTION : ne pas faire un chercher -> remplacer de `SDK-GO` par `<nom du projet>`, le fork du projet doit continuer d'inclure certaines dépendances vers le projet SDK-GO afin de bénéficier de ces dernières mises à jour et de toutes ces fonctionnalités.

Pour remplacer les mentions "SDK-GO" par le nom du projet éléments sont nécéssaires :

- nom-du-projet : le nom donné au projet
- nom-du-dépôt : le nom du projet tel qu'il apparaît dans l'url sur la forge
- hostname-du-projet : l'url attribué au projet (dans le cadre du développement il est intéréssant de garder une adresse .nip.io)

Dans le fichier `.env` modifier la variable `HOSTNAME=sdk-go.127.0.0.1.nip.io` => `HOSTNAME=<hostname-du-projet>.127.0.0.1.nip.io`

Dans le fichier `docker-compose.yml` remplacer `sdk-go-container:` par `<nom-du-projet>-container:` et `image: sdk-go` par `image : <nom-du-projet>`

Dans le fichier `main.go` remplacer

```go
"forge.grandlyon.com/apoyen/sdk-go/internal/mocks" => "forge.grandlyon.com/apoyen/<nom-du-dépôt>/internal/mocks"
"forge.grandlyon.com/apoyen/sdk-go/internal/rootmux" => "forge.grandlyon.com/apoyen/<nom-du-dépôt/internal/rootmux"
```

Dans le fichier `dev_certificates/domains.ext` remplacer `DNS.4 = sdk-go.127.0.0.1.nip.io:1443` => `DNS.4 = <hostname-du-projet>.127.0.0.1.nip.io:1443`

Dans le fichier `internal/models/models.go`, remplacer :

```go
"forge.grandlyon.com/apoyen/sdk-go/internal/auth" => "forge.grandlyon.com/apoyen/<nom-du-dépôt>/internal/auth"
```

Dans le fichier `internal/rootmux/rootmux_test.go` remplacer :

```go
"forge.grandlyon.com/apoyen/sdk-go/internal/auth" => "forge.grandlyon.com/apoyen/<nom-du-dépôt>o/internal/auth"
"forge.grandlyon.com/apoyen/sdk-go/internal/mocks" => "forge.grandlyon.com/apoyen/<nom-du-dépôt>/internal/mocks"
```

Dans le fichier `internal/rootmux/rootmux.go`, remplacer :

```go
"forge.grandlyon.com/apoyen/sdk-go/internal/auth" => "forge.grandlyon.com/apoyen/<nom-du-dépôt>/internal/auth"
"forge.grandlyon.com/apoyen/sdk-go/internal/models" => "forge.grandlyon.com/apoyen/<nom-du-dépôt>/internal/models"
```

Dans le fichier `web/index.html` remplacer `<title>SDK-GO</title>` => `<title><nom-du-projet></title>` et `https://forge.grandlyon.com/apoyen/sdk-go` => `https://forge.grandlyon.com/apoyen/<nom-du-dépot>`

Dans le fichier `web/assets/brand/brand.js`, remplacer :

```javascript
export const windowTitle = "SDK-GO"; => export const windowTitle = "<nom-du-projet>";
export const navTitle = "SDK-GO"; => export const navTitle = "<nom-du-projet>";
```

Dans le fichier `web/assets/brand/manifest.js`, remplacer :

```javascript
"name": "SDK-GO" => "name": "<nom-du-projet>",,
"short_name": "SDK-GO" => "short_name": "<nom-du-projet>",,
```

### Définition du modèle

C'est dans le fichier `models.go` que doit être définit le modèle de donnée de l'application.
Alexis POYEN's avatar
Alexis POYEN committed
152
153
154
155
156
157
158
159
160

## Contribution

Un bug découvert ? Une demande d'amélioration ? Une contribution à la dcoumentation ?

Utilisé le système d'issue pour expliquer votre découverte ou votre poposition.

Vous voulez contribuez directement au code ? 

Alexis POYEN's avatar
Alexis POYEN committed
161
Créer une issue pour expliquer votre contribution, créer une branche à partir de cette issue, développer votre fonctionnalité sur la branche et faite une merge request.