README.md 7.88 KB
Newer Older
ivan's avatar
ivan committed
1
# MoodleNet Web Client
Mayel's avatar
Mayel committed
2

3
This React project was bootstrapped with [Create React App](https://create-react-app.dev/) with [CRA Typescript](https://create-react-app.dev/docs/adding-typescript/) template.
Sam Gluck's avatar
Sam Gluck committed
4

Mayel's avatar
Mayel committed
5
## Index
Sam Gluck's avatar
Sam Gluck committed
6

ivan's avatar
ivan committed
7
- [Deploying MoodleNet](#deploying-moodlenet)
Sam Gluck's avatar
Sam Gluck committed
8
- [Structure](#structure)
9 10
  - [High level folder structure](#high-level-folder-structure)
  - [Application source folder structure](#application-source-folder-structure)
Mayel's avatar
Mayel committed
11
- [Development Scripts](#development-scripts)
12 13 14 15 16
  - [`yarn start`](#yarn-start)
  - [`yarn add-locale`](#yarn-add-locale)
  - [`yarn extract`](#yarn-extract)
  - [`yarn compile`](#yarn-compile)
  - [`yarn build`](#yarn-build)
Sam Gluck's avatar
Sam Gluck committed
17 18
- [Libraries](#libraries)

ivan's avatar
ivan committed
19
## Deploying MoodleNet
Mayel's avatar
Mayel committed
20 21 22 23 24 25 26 27

### Install using Docker containers (recommended)

1. Make sure you have [Docker](https://www.docker.com/), a recent [docker-compose](https://docs.docker.com/compose/install/#install-compose) (which supports v3 configs) installed:

```sh
$ docker version
Docker version 18.09.1-ce
28
$ docker-compose -v
Mayel's avatar
Mayel committed
29 30 31 32 33
docker-compose version 1.23.2
...
```

2. Clone this repository and change into the directory:
34

Mayel's avatar
Mayel committed
35
```sh
Noel De Martin's avatar
Noel De Martin committed
36
$ git clone https://gitlab.com/moodlenet/frontend.git moodlenet
Alessandro Giansanti's avatar
Alessandro Giansanti committed
37
...
ivan's avatar
ivan committed
38
$ cd moodlenet
Mayel's avatar
Mayel committed
39 40
```

Mayel's avatar
Mayel committed
41
3. Configuration
Mayel's avatar
Mayel committed
42 43 44

First make sure to configure your domain name or subdomain to point to your server's IP address.

Alessandro Giansanti's avatar
Alessandro Giansanti committed
45
We need to set some environment variables in order for MoodleNet to function, a list of which can be found in these files: - `.env` - If you have a domain configured to point to your server, replace every instance of 'localhost' with 'your-domain-here.tld' and those of 'http:' with 'https:' (the 's' is critical) - **If you want to connect your instance with the MoodleNet "mothership" for indexing public content, search, and discovery**, and you agree with the [Terms for Instance Administrators](https://moodle.net/terms/admins/index.html), set CONNECT_WITH_MOTHERSHIP to true, otherwise set it to false. You should then email moodlenet-moderators@moodle.com to request an API key. - `.env.secrets.example` (which you must copy to `.env.secrets`) - set each password and secret with something random and secure - MAIL_DOMAIN and MAIL_KEY are needed to configure transactional email, sign up at [Mailgun](https://www.mailgun.com/) and then configure the domain name and key
Mayel's avatar
Mayel committed
46 47 48

4. Once configured, build the docker image:

Alessandro Giansanti's avatar
Alessandro Giansanti committed
49
```sh
Mayel's avatar
Mayel committed
50
$ docker-compose build
Alessandro Giansanti's avatar
Alessandro Giansanti committed
51
...
Mayel's avatar
Mayel committed
52
```
Mayel's avatar
Mayel committed
53

Doug Belshaw's avatar
Doug Belshaw committed
54
Or if you're building on a Raspberry Pi:
55

Alessandro Giansanti's avatar
Alessandro Giansanti committed
56
```sh
Mayel's avatar
Mayel committed
57
$ docker-compose -f docker-compose.pi.yml build
Alessandro Giansanti's avatar
Alessandro Giansanti committed
58
...
Mayel's avatar
Mayel committed
59 60
```

61
5. Try it out
Mayel's avatar
Mayel committed
62

Mayel's avatar
Mayel committed
63 64
a) run the backend in console mode: `docker-compose run --rm backend bin/moodle_net start_iex`

Mayel's avatar
Mayel committed
65
b) if you're in invite-only mode, add your email to the allowlist in order to be able to sign up: `MoodleNet.Access.create_register_email("myemail@domain.com")` and then exit (Ctrl+C and then `abort`)
Mayel's avatar
Mayel committed
66 67

c) Start the docker containers with docker-compose:
Mayel's avatar
Mayel committed
68 69 70

```sh
$ docker-compose up
Alessandro Giansanti's avatar
Alessandro Giansanti committed
71
...
Mayel's avatar
Mayel committed
72 73
```

Doug Belshaw's avatar
Doug Belshaw committed
74
Or if you're running on a Raspberry Pi:
75

Alessandro Giansanti's avatar
Alessandro Giansanti committed
76
```sh
Mayel's avatar
Mayel committed
77
$ docker-compose -f docker-compose.pi.yml up
Alessandro Giansanti's avatar
Alessandro Giansanti committed
78
...
Mayel's avatar
Mayel committed
79 80
```

Alessandro Giansanti's avatar
Alessandro Giansanti committed
81 82
6. The MoodleNet backend and frontend should now be running at [http://localhost/](http://localhost/) on your machine and at `https://your-domain-name.tld/` with SSL certificates automatically configured thanks to letsencrypt.org (if your domain was correctly configured).
   Once you've signed up, you may want to make yourself an instance admin, by running this in the backend console (see above): `MoodleNet.ReleaseTasks.make_instance_admin("your_username")`
Mayel's avatar
Mayel committed
83

Mayel's avatar
Mayel committed
84
7. If that worked, start the app as a daemon next time:
85

Mayel's avatar
Mayel committed
86 87
```sh
$ docker-compose up -d
Alessandro Giansanti's avatar
Alessandro Giansanti committed
88
...
Mayel's avatar
Mayel committed
89 90
```

Doug Belshaw's avatar
Doug Belshaw committed
91
Or if you're running on a Raspberry Pi:
92

Alessandro Giansanti's avatar
Alessandro Giansanti committed
93
```sh
Mayel's avatar
Mayel committed
94
$ docker-compose -f docker-compose.pi.yml up -d
Alessandro Giansanti's avatar
Alessandro Giansanti committed
95
...
Mayel's avatar
Mayel committed
96 97
```

Sam Gluck's avatar
Sam Gluck committed
98 99
## Structure

Alessandro Giansanti's avatar
Alessandro Giansanti committed
100
### High level folder structure
Sam Gluck's avatar
Sam Gluck committed
101

102 103 104 105 106
| Folder    | Description                                                       |
| --------- | ----------------------------------------------------------------- |
| `/build`  | the output directory containing static assets & application files |
| `/public` | files that will be copied into the `build` folder                 |
| `/src`    | the application source                                            |
Sam Gluck's avatar
Sam Gluck committed
107

Alessandro Giansanti's avatar
Alessandro Giansanti committed
108
### Application source folder structure
Sam Gluck's avatar
Sam Gluck committed
109

110 111 112 113 114 115 116 117 118 119 120 121
| Folder              | Description                                                                                                                  |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `/src/apollo`       | all (react-)apollo boilerplate, type definitions, and resolvers                                                              |
| `/src/containers`   | high-level react container components which handle routing, state, and main set-ups                                          |
| `/src/graphql`      | contains main schema generated typings                                                                                       |
| `/src/locales`      | locale folders define the available locales (managed by linguijs) and each contains its locale's language data               |
| `/src/static`       | static assets such as images that are used within the application code (for example, images can be `require`'d with webpack) |
| `/src/ui`           | UI components                                                                                                                |
| `/src/ctrl`         | Controllers components for UI                                                                                                |
| `/src/routes`       | Routing components interfacing React-Router to main Page-Controllers                                                         |
| `/src/fe`           | Controller's hooks APIs                                                                                                      |
| `/src/mn-constants` | Hard-coded and build-env constants                                                                                           |
Sam Gluck's avatar
Sam Gluck committed
122

Mayel's avatar
Mayel committed
123
## Development Scripts
Sam Gluck's avatar
Sam Gluck committed
124 125 126

In the project directory, you can run:

Mayel's avatar
Mayel committed
127
### `yarn start`
Sam Gluck's avatar
Sam Gluck committed
128

Sam Gluck's avatar
Sam Gluck committed
129
Runs the app in the development mode.
Sam Gluck's avatar
Sam Gluck committed
130 131
Open [http://localhost:3000](http://localhost:3000) to view it in the browser.

Sam Gluck's avatar
Sam Gluck committed
132
The page will reload if you make edits.
Sam Gluck's avatar
Sam Gluck committed
133 134
You will also see any lint errors in the console.

Mayel's avatar
Mayel committed
135
### `yarn add-locale`
Mayel's avatar
Mayel committed
136

137
Adds a locale for localisation, with [lingui library](https://lingui.js.org/ref/react.html).
Mayel's avatar
Mayel committed
138

Mayel's avatar
Mayel committed
139
### `yarn extract`
Mayel's avatar
Mayel committed
140

Alessandro Giansanti's avatar
Alessandro Giansanti committed
141
Extracts new/updated strings from the codebase into JSON files for localisation (they need to be encapsulated with [lingui library](https://lingui.js.org/ref/react.html)'s `<Trans>`).
Mayel's avatar
Mayel committed
142

Mayel's avatar
Mayel committed
143
### `yarn compile`
Mayel's avatar
Mayel committed
144

145
Compiles localisation files for production.
Mayel's avatar
Mayel committed
146

Mayel's avatar
Mayel committed
147
### `yarn build`
Sam Gluck's avatar
Sam Gluck committed
148

149
Builds the app for production to the `build` folder.
Sam Gluck's avatar
Sam Gluck committed
150 151
It correctly bundles React in production mode and optimizes the build for the best performance.

152 153 154 155 156 157 158 159
The build is minified and the filenames include the hashes.

### `yarn storybook`

Builds a `Storybook` static app out of the storybook's `tsx`|`mdx` modules associated to UI components

### `yarn gqlcode`

Alessandro Giansanti's avatar
Alessandro Giansanti committed
160
Generates typed modules based on `src/**/*.graphql` files and `.env.development`'s `REACT_APP_GRAPHQL_ENDPOINT` Backend GraphQL exposed schema.
Sam Gluck's avatar
Sam Gluck committed
161

Sam Gluck's avatar
Sam Gluck committed
162
## Libraries
Sam Gluck's avatar
Sam Gluck committed
163

164 165
This section mentions notable libraries and tools used within the application and provides links to their documentation.

Alessandro Giansanti's avatar
Alessandro Giansanti committed
166 167 168 169 170 171 172 173
- React, UI framework [https://reactjs.org/docs/getting-started.html](https://reactjs.org/docs/getting-started.html)
- TypeScript, programming language [https://www.typescriptlang.org](https://www.typescriptlang.org)
- webpack, build tool [https://webpack.js.org](https://webpack.js.org)
- React Apollo, GraphQL client [https://www.apollographql.com/docs/react/](https://www.apollographql.com/docs/react/)
- Phoenix.js, Phoenix channels JS client [https://hexdocs.pm/phoenix/js/index.html](https://hexdocs.pm/phoenix/js/index.html)
- GraphQL Code Generator [https://graphql-code-generator.com/](https://graphql-code-generator.com/)
- Formik form management [https://formik.org/](https://formik.org/)
- LinguiJs localisation library [https://lingui.js.org/](https://lingui.js.org/)