Skip to content

Commit

Permalink
Merge pull request #455 from blacksponge/update-readme
Browse files Browse the repository at this point in the history 
Update gui readme
  • Loading branch information
@hannaeko
hannaeko authored Jan 25, 2024
2 parents 35bc368 + 2a1ee77 commit a25359c
Showing 1 changed file with 52 additions and 75 deletions.
127 changes: 52 additions & 75 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,14 +1,12 @@
Zonemaster Web GUI [![Build Status](https://app.travis-ci.com/zonemaster/zonemaster-gui.svg?branch=master)](https://app.travis-ci.com/zonemaster/zonemaster-gui)
==========
# Zonemaster Web GUI [![CI status](https://github.com/zonemaster/zonemaster-gui/actions/workflows/ci.yml/badge.svg)](https://github.com/zonemaster/zonemaster-gui/actions/workflows/ci.yml)

### Purpose
This module is the Web Interface part of the Zonemaster project.

### Installation
### Purpose

Follow the detailed [installation instructions].
This module is the Web Interface part of the Zonemaster project. For an
overview of the Zonemaster software, please see the [Zonemaster repository].

##### Prerequisites
### Prerequisites

Before you install the Zonemaster Web GUI module, you need the Zonemaster
Engine test framework installed. Please see the [Zonemaster-Engine
Expand All @@ -17,95 +15,73 @@ installation] document.
You also need a running Zonemaster-Backend component. Please see the
[Zonemaster-Backend installation] document.

##### Configuration
### Installation

Follow the detailed [installation instructions].

### Configuration

The configuration instructions for the backend can be found in the [Backend
The configuration instructions for the Backend can be found in the [Backend
configuration] document.

The configuration instructions for the GUI can be found in the [GUI
configuration] document.

### Documentation

There is a [public documentation]. Some more specific documents can be found in
the [docs directory](docs/).

### Contribution

This project was generate with Angular-CLI 1.6.8 and then updating.
It use the Angular 2+ framework with all its tools.

The source code of the application is available in ``./src/app`` folder.
The ``app`` folder is structured as follow :
```
+-- components
+-- models
| +-- alter.ts : Alert model (level, message)
| +-- index.ts : module export
+-- pipes
| +-- filer.pipe.* : Filter a list based on a string
| +-- filer-by-categories.pipe.* : Filter the list of result by categories
| +-- romanize.pipe.* : Transform latin number to roman number (1 -> I, 2 -> II)
| +-- safe-html.pipe.* : Sanitize text to HTML
+-- services
| +-- alert.service.* : to display alert messages
| +-- app.service.* : to manage app configuration (api url, etc.)
| +-- dns-check.service.* : to communicate with the Zonemaster Backend API
+-- app.*
```

The ``components`` folder is composed of subfolders that represent the main components.
Each folder of component contain three files :
- ``*.component.css`` : The component's style
- ``*.component.html`` : The component's html
- ``*.component.ts`` : The component's typescript

All assets are available in ``src/assets`` folder.
It's split by concern, all translation files are in the ``i18n`` folder, the style in the ``css``,
images are in the ``images`` folder, etc.

The configurations files of the application are in the ``src/environments`` folder.
``environment.ts`` is use for development purpose, and the ``environment.prod.ts`` for production.

In order to contribute
This project was generated with Angular-CLI 1.6.8.
It uses the Angular 2+ framework with all its tools.

The source code of the application is available in `./src/app` folder.

The `components` folder is composed of subfolders that represent the main
components. Each folder of component contain three files:

* `*.component.css`: the component's style configuration;
* `*.component.html`: the component's HTML code;
* `*.component.ts`: the component's TypeScript code.

All assets are available in the `src/assets` folder. It is split by concern;
the style configurations are in the `css`, images are in the `images` folder, etc.

All translation files are in the `src/locale` folder.

The environment defaults of the application are in the `src/environments`
folder. `environment.ts` is used for development purposes, the
`environment.prod.ts` for production, and the `environment.test.ts` for testing.

In order to contribute:

* Install [Nodejs](https://nodejs.org)
* Fork the Zonemaster GUI repository on Github into your own user on Github.
* Clone your fork to your working environment.
* Go to the folder and install project dependencies with `npm install`
* Update environment files in `/src/environments/` to add a backend api endpoint (or leave the default)
* Update configuration files in `src/assets/app.config.json` to add a Backend
API endpoint (or leave the default)
* Make your changes, test them and push them to your fork on Github
* From your fork, make a Pull Request against the zonemaster/zonemaster-gui repository.
Please always make the Pull Request against the develop branch.

* From your fork, make a Pull Request against the zonemaster/zonemaster-gui
repository. Please always make the Pull Request against the develop branch.
* Thank you for your contribution!

> In development mode, you probably have to enable [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) on your browser.
> The Cross-Origin Resource Sharing (CORS) performed by the browser blocks every AJAX request that does not match the exact host, protocol, and port of your site.
##### Development server
Run `npm start` for a dev server. Navigate to `http://localhost:4200/`. The app will automatically reload if you change any of the source files.
#### Development server

##### Build
Run `npm run build` to build the project. The build artifacts will be stored in the `dist/` directory.
The script also change the FAQ markdown files to html files.
Run `npm start` for a dev server. Navigate to `http://localhost:4200/en`.
The app will automatically reload if you change any of the source files.

##### Test
See [Testing](docs/Testing.md).
#### Build

##### Create a release zip file
Run 'npm run release' to create a zip file with dist folder and zonemaster.conf file. Then upload it in github.

### Documentation

There is a [public documentation]. Some more specific documents can be found in
the [docs directory](docs/).
Run `npm run build` to build the project. The build artifacts will be stored in the `dist/` directory.

#### Security of our dependencies
Based on the output of [david](https://david-dm.org/) and [npm audit](https://docs.npmjs.com/cli/audit), we reguraly
update our dependencies with the latest secure version. Notice that we can't follow the rythm of new versions, so you could
get security warning during the installation of development dependencies.
#### Test

#### Acknowledge
This project was generated with [Angular CLI](https://github.com/angular/angular-cli) version 1.6.8.
See [Testing](docs/Testing.md).

License
=======
## License

This is free software under a 2-clause BSD license. The full text of the license can
be found in the [LICENSE](LICENSE) file included in this respository.
Expand All @@ -117,6 +93,7 @@ are taken from <https://undraw.co>, [full license](https://undraw.co/license).
[Backend Configuration]: https://github.com/zonemaster/zonemaster/blob/master/docs/public/configuration/backend.md
[GUI Configuration]: https://github.com/zonemaster/zonemaster/blob/master/docs/public/configuration/gui.md
[Installation instructions]: https://github.com/zonemaster/zonemaster/blob/master/docs/public/installation/zonemaster-gui.md
[Public documentation]: https://github.com/zonemaster/zonemaster/blob/master/README.md#documentation
[Public documentation]: https://github.com/zonemaster/zonemaster/blob/master/docs/public/README.md
[Zonemaster-Engine installation]: https://github.com/zonemaster/zonemaster/blob/master/docs/public/installation/zonemaster-engine.md
[Zonemaster-Backend installation]: https://github.com/zonemaster/zonemaster/blob/master/docs/public/installation/zonemaster-backend.md
[Zonemaster repository]: https://github.com/zonemaster/zonemaster

0 comments on commit a25359c

Please sign in to comment.