Fakultas Ilmu Komputer UI

README.md 6.77 KB
Newer Older
Giovan Isa Musthofa's avatar
Giovan Isa Musthofa committed
1
2
3
4
5
# Akun

![pipeline-badge](https://gitlab.cs.ui.ac.id/kp-itf/2020/authentication-as-a-service/stable/akun/badges/master/pipeline.svg?job=Unit%20Tests&style=flat-square)
![coverage-badge](https://gitlab.cs.ui.ac.id/kp-itf/2020/authentication-as-a-service/stable/akun/badges/master/coverage.svg?job=Unit%20Tests&style=flat-square)

6
7
8
9
10
11
12
13
## Requirements

* Python (3.6, 3.7, 3.8)
* Django (3.1)

We **highly recommend** and only officially support the latest patch release of
each Python and Django series.

Giovan Isa Musthofa's avatar
Giovan Isa Musthofa committed
14
## Setup Local Development
15

16
17
Run a standalone akun service. To run it together with CAS and the whole gang,
please read [Setup Local docker-compose](#setup-local-docker-compose)
18

19
1.  Create python3's virtual environment and activate it.
Giovan Isa Musthofa's avatar
Giovan Isa Musthofa committed
20
21

```bash
22
23
python3 -m venv venv
source venv/bin/activate
Giovan Isa Musthofa's avatar
Giovan Isa Musthofa committed
24
25
```

26
2.  Install development packages
Giovan Isa Musthofa's avatar
Giovan Isa Musthofa committed
27
28

```bash
29
pip install -r requirements-dev.txt
30
pre-commit install
31
32
```

33
34
35
3.  Using the `manage.py` script and subsequently the `akun.settings.debug`
    module as `DJANGO_SETTINGS_MODULE` by default wouldn't require any
    environment variables to run unit tests and development server.
36

37
38
39
40
41
42
    Using the debug settings, you will have Django's console email backend,
    MockLdapBackend with entries from `mock-entries.json`, and reCAPTCHA's
    testing public and private key.

    See the required envs for production/container settings, explained
    [below](#environment-variables).
43

44
4.  Run unit tests and show coverages
45
46

```bash
47
coverage run --source='akun,csaccountmanagement,rest_apereo_cas' -m pytest
48
49
50
coverage report --show-missing --skip-covered
```

51
52
53
54
55
56
57
58
59
60
61
5.  Setup the database. By default it is set to `db.sqlite3` file. You can always
    use `DATABASE_URL` env variable to override the database connection. Mind you
    that this project use extensively Django's 3.1 `JSONField` attribute. So,
    make sure the actual database instance supports it.

    Run the migration command and you are good to go.

```bash
python3 ./manage.py migrate
```

62
63
64
65
66
67
68
6.  Load sitetree's sitetreedump-ed json data

```bash
python3 ./manage.py sitetreeload --mode=replace sitetree.json
```

7.  Run development server
69
70
71
72
73
74

```bash
python3 ./manage.py runserver
```


75
8.  Open generated portray docs in browser
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95

```bash
portray in_browser
```

## Setup Local docker-compose

> __Note__: This is http only setup suitable for local debugging. However, it
> still has some problems dealing with CAS's HTTPS redirection behind proxy.

1.  Set environment variables. Though most environment variables has been set to
    their safe defaults. The secret ones are better set using `env_file` key.

    On compose.env file, set sensitive environment variables such as
    `LDAP_SERVER_URI`, `LDAP_BASE_DN`, `LDAP_BASE_DN_MAHASISWA`,
    `LDAP_BASE_DN_STAF`, `LDAP_USER`, `LDAP_PASSWORD`, `RECAPTCHA_PUBLIC_KEY`,
    `RECAPTCHA_PRIVATE_KEY`, etc.

2.  Bring up the services by running the command below. This might take a
    while to pull and build all the container images.
96
97
98

```bash
docker-compose up -d
Giovan Isa Musthofa's avatar
Giovan Isa Musthofa committed
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
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181

3.  Prepare the database once the `akun` service is running, Run the migration
    command to apply the database migrations.

```bash
docker-compose exec akun ./manage.py migrate
```

4.  Create staff/superuser User account using the same credential defined in
    `examples/application.yml` file at `cas.serviceRegistry.rest` key. Run the
    command below to interactively create one.

```bash
docker-compose exec akun ./manage.py createsuperuser
```

5.  Attach terminal to the services logs by running the command below.

```bash
docker-compose logs -f
```

## Guideline for Production Deployment

1.  The project artifacts are container images. This is to allow much easier
    deployment to container based solution such as docker-compose, Swarm, or
    Kubernetes.

2.  Persists data and state using volumes. Using container means you are working
    with ephemeral filesystems. Make sure your database container filesystem is
    mounted on persistent volume.

3.  [Proxy](topics/proxy-configuration) is a major component. Make sure it:

    - Routes correctly to all service endpoints based on prefix path
    - Has TLS enabled, correctly set the security headers, and ssl redirect
    - Sets and pass the correct proxy headers to services
    - Accepts proxy headers only from trusted IPs

4.  Make sure Service Discovery (or DNS) is working properly for communication
    between services. This is critical for CAS service communication to akun
    service via HTTP.

5.  Next is to configure each service individual settings.
    [CAS properties](topics/cas-configuration) can be set using
    `application.yml`. On the other hand, akun service can be configured
    to some degree using the [environment variables](#environment-variables).

## Environment Variables

### Required

This is required to run the development server. Why required? Because as of now
there's no way to mock / turn this off.

| Variable                 | Description                               | Secret |
| ------------------------ | ----------------------------------------- | ------ |
| `LDAP_SERVER_URI`        | LDAP's server uri e.g. (ldap://127.0.0.1) |        |
| `LDAP_BASE_DN`           | LDAP's base directory                     |        |
| `LDAP_USER`              | LDAP's manager to authenticate as         |        |
| `LDAP_PASSWORD`          | `LDAP_USER` password                      | v      |
| `RECAPTCHA_PUBLIC_KEY`   | Google's reCAPTCHA public key             |        |
| `RECAPTCHA_PRIVATE_KEY`  | Google's reCAPTCHA private key            | v      |

### Production Usage

| Variable              | Description                                                         | Secret |
| --------------------- | ------------------------------------------------------------------- | ------ |
| `SECRET_KEY`          | Secret key to persist users's session, sign cookies and many more   | v      |
| `DATABASE_URL`        | External database uri (e.g. `postgres://akun:akunpassword@db/akun`) | v      |
| `ALLOWED_HOSTS`       | Semicolon (`;`) delimited list of allowed hosts                     |        |
| `DEFAULT_FROM_EMAIL`  | Sender for confirmation email (e.g. `noreply@cs.ui.ac.id`)          |        |
| `EMAIL_HOST`          | Host running the smtp email service                                 |        |
| `EMAIL_HOST_USER`     | Username to authenticate to smtp email service                      |        |
| `EMAIL_HOST_PASSWORD` | Password to authenticate to smtp email service                      | v      |
| `EMAIL_PORT`          | Smtp email service custom port                                      |        |
| `WORKERS`             | The number of gunicorn workers                                      |        |

## Credentials and Sensitive Files for Production Environment

For production environment, several values can be requested by contacting
[itf@cs.ui.ac.id](mailto:itf@cs.ui.ac.id).