gns3-web-ui/README.md

# gns3-web-ui

![Build](https://github.com/GNS3/gns3-web-ui/actions/workflows/main.yml/badge.svg)
[![Dependency](https://img.shields.io/librariesio/github/GNS3/gns3-web-ui)](https://libraries.io/github/GNS3/gns3-web-ui)
[![Packages versions](https://repology.org/badge/latest-versions/gns3.svg)](https://repology.org/metapackage/gns3/versions)
[![Packages](https://repology.org/badge/tiny-repos/gns3.svg)](https://repology.org/metapackage/gns3/versions)

## Demo

Please use GNS3 WebUI bundled in `gns3server` and `gns3`.

## Development

### Branches policy

On branch `master` you can find the latest codebase including under development features. If you are looking for stable version with features promoted to be included in the current/next release please switch to `stable` branch.

### Installation

We're using [yarn](https://yarnpkg.com/lang/en/) for packages installation:

```
yarn install
```

## JavaScript heap out of memory

Increase the memory allocated to Node if you get JavaScript heap out of memory errors.

```
export NODE_OPTIONS=--max-old-space-size=8192
```

#### Run GNS3 server

Visit [gns3-server](https://github.com/GNS3/gns3-server) for guide how to run GNS3 server.

#### Run WebUI

```
yarn ng serve
``` 

Application is accessible on `http://127.0.0.1:4200/`. The app will automatically reload if you change any of the source files.

### Docker container

For development you can also run the GNS3 Web UI in a container

```
bash scripts/docker_dev_webui.sh
```

### How to upgrade package.json?

```
yarn upgrade --latest
```

### gns3server bundled in WebUI - electron based

In special cases it's possible to build `gns3server` for GNS3 WebUI. This version is included in `electronjs` dist application.

```
python3 scripts/build.py build -b dist
```

### Code scaffolding

Run `yarn ng generate component component-name` to generate a new component. You can also use `yarn ng generate directive|pipe|service|class|module`.

### Build

Run `yarn ng build` to build the project. The build artifacts will be stored in the `dist/` directory. Use the `-prod` flag for a production build.

### Running unit tests

Run `yarn ng test` to execute the unit tests via [Karma](https://karma-runner.github.io).


## Releasing

### Release naming convention

Releases are named by the year and quarter when release is happening, e.g. January 2020 release is named 2020.1.X.

### Bumping releases

We're using [version-bump-prompt](https://www.npmjs.com/package/version-bump-prompt) for increasing version.

Install `version-bump-prompt` via:

        npm install -g version-bump-prompt
        
If you would like to bump prepatch just type:

        bump --prepatch --tag --push
        
### Distribute release

We have got configured CircleCI, TravisCI and AppVeyor for distributing application for particular platform. In order to release you need to tag&push your changes from master.

First of all please remove `dev` from version in `package.json` (for instance `2019.2.0-alpha.4dev` to `2019.2.0-alpha.4`). Commit & push changes with message `Release 2019.2.0-alpha.4` . Next step is to tag repository and push to origin:


        git tag v2019.2.0-alpha.4
        git push origin v2019.2.0-alpha.4
        

When artifacts are made you can see draft release here: [gns3-web-ui releases](https://github.com/GNS3/gns3-web-ui/releases) which is waiting to be published.
After release please change current version in `package.json` to `2019.2.0-alpha.5dev`'. Otherwise artifacts will be overwritten during the next commit. Don't forget to commit & push changes.

#### Updating gns3server

Checkout the latest master of `gns3server`. Run command `./scripts/update-bundled-web-ui.sh --tag=v2019.2.0-alpha.5`. Commit & push changes with message `Release 2019.2.0-alpha.4`.

### Staging release

In case you would like to create a new staging release. Please create draft release on github, like `0.0.1-dev1`. After successful build you can find artifacts there. 

### Updating signing certificate for Windows

Please follow this guide: [code-signing](https://www.electron.build/code-signing), use `certmgr.msc` exporting tool to limit the size of certificate.

## Further help

If you want to contribute to GNS3 Web UI feel free to reach us at `developers@gns3.net`.
Initial commit 2017-09-25 09:27:22 +00:00			`# gns3-web-ui`
Draft of WebUI 2017-09-25 11:07:52 +00:00
Update README.md 2021-04-19 10:16:33 +00:00			`![Build](https://github.com/GNS3/gns3-web-ui/actions/workflows/main.yml/badge.svg)`
Update README.md This quickly shows all package versions across different distros at a glance. Also, Libraries.io dependency status for GitHub repo. 2020-09-16 10:26:17 +00:00			`[![Dependency](https://img.shields.io/librariesio/github/GNS3/gns3-web-ui)](https://libraries.io/github/GNS3/gns3-web-ui)`
			`[![Packages versions](https://repology.org/badge/latest-versions/gns3.svg)](https://repology.org/metapackage/gns3/versions)`
			`[![Packages](https://repology.org/badge/tiny-repos/gns3.svg)](https://repology.org/metapackage/gns3/versions)`
docs(readme): add Greenkeeper badge 2018-01-23 08:19:04 +00:00
Disable LocationStrategies if on electron/non-electron, README update 2018-07-16 08:28:45 +00:00			`## Demo`
Draft of WebUI 2017-09-25 11:07:52 +00:00
Disable LocationStrategies if on electron/non-electron, README update 2018-07-16 08:28:45 +00:00			Please use GNS3 WebUI bundled in `gns3server` and `gns3`.
Draft of WebUI 2017-09-25 11:07:52 +00:00
Disable LocationStrategies if on electron/non-electron, README update 2018-07-16 08:28:45 +00:00			`## Development`
Draft of WebUI 2017-09-25 11:07:52 +00:00
Update README with branches policy 2018-12-10 11:37:17 +00:00			`### Branches policy`

			On branch `master` you can find the latest codebase including under development features. If you are looking for stable version with features promoted to be included in the current/next release please switch to `stable` branch.

Disable LocationStrategies if on electron/non-electron, README update 2018-07-16 08:28:45 +00:00			`### Installation`
Draft of WebUI 2017-09-25 11:07:52 +00:00
Disable LocationStrategies if on electron/non-electron, README update 2018-07-16 08:28:45 +00:00			`We're using [yarn](https://yarnpkg.com/lang/en/) for packages installation:`
Draft of WebUI 2017-09-25 11:07:52 +00:00
Disable LocationStrategies if on electron/non-electron, README update 2018-07-16 08:28:45 +00:00			```
			`yarn install`
			```
Draft of WebUI 2017-09-25 11:07:52 +00:00
Update README.md 2021-04-06 10:24:52 +00:00			`## JavaScript heap out of memory`

			`Increase the memory allocated to Node if you get JavaScript heap out of memory errors.`

			```
			`export NODE_OPTIONS=--max-old-space-size=8192`
			```

Disable LocationStrategies if on electron/non-electron, README update 2018-07-16 08:28:45 +00:00			`#### Run GNS3 server`
Draft of WebUI 2017-09-25 11:07:52 +00:00
Disable LocationStrategies if on electron/non-electron, README update 2018-07-16 08:28:45 +00:00			`Visit [gns3-server](https://github.com/GNS3/gns3-server) for guide how to run GNS3 server.`
Draft of WebUI 2017-09-25 11:07:52 +00:00
Disable LocationStrategies if on electron/non-electron, README update 2018-07-16 08:28:45 +00:00			`#### Run WebUI`
Draft of WebUI 2017-09-25 11:07:52 +00:00
			```
Disable LocationStrategies if on electron/non-electron, README update 2018-07-16 08:28:45 +00:00			`yarn ng serve`
Draft of WebUI 2017-09-25 11:07:52 +00:00			```

Disable LocationStrategies if on electron/non-electron, README update 2018-07-16 08:28:45 +00:00			Application is accessible on `http://127.0.0.1:4200/`. The app will automatically reload if you change any of the source files.
Draft of WebUI 2017-09-25 11:07:52 +00:00
Add Dockerfile for development 2018-02-21 12:21:32 +00:00			`### Docker container`

Disable LocationStrategies if on electron/non-electron, README update 2018-07-16 08:28:45 +00:00			`For development you can also run the GNS3 Web UI in a container`
Add Dockerfile for development 2018-02-21 12:21:32 +00:00
Disable LocationStrategies if on electron/non-electron, README update 2018-07-16 08:28:45 +00:00			```
			`bash scripts/docker_dev_webui.sh`
			```
Add Dockerfile for development 2018-02-21 12:21:32 +00:00
Disable LocationStrategies if on electron/non-electron, README update 2018-07-16 08:28:45 +00:00			`### How to upgrade package.json?`
Draft of WebUI 2017-09-25 11:07:52 +00:00
Disable LocationStrategies if on electron/non-electron, README update 2018-07-16 08:28:45 +00:00			```
			`yarn upgrade --latest`
			```
Draft of WebUI 2017-09-25 11:07:52 +00:00
Disable LocationStrategies if on electron/non-electron, README update 2018-07-16 08:28:45 +00:00			`### gns3server bundled in WebUI - electron based`
Draft of WebUI 2017-09-25 11:07:52 +00:00
Disable LocationStrategies if on electron/non-electron, README update 2018-07-16 08:28:45 +00:00			In special cases it's possible to build `gns3server` for GNS3 WebUI. This version is included in `electronjs` dist application.
Draft of WebUI 2017-09-25 11:07:52 +00:00
Disable LocationStrategies if on electron/non-electron, README update 2018-07-16 08:28:45 +00:00			```
			`python3 scripts/build.py build -b dist`
			```
Draft of WebUI 2017-09-25 11:07:52 +00:00
Disable LocationStrategies if on electron/non-electron, README update 2018-07-16 08:28:45 +00:00			`### Code scaffolding`
Draft of WebUI 2017-09-25 11:07:52 +00:00
Disable LocationStrategies if on electron/non-electron, README update 2018-07-16 08:28:45 +00:00			Run `yarn ng generate component component-name` to generate a new component. You can also use `yarn ng generate directive\|pipe\|service\|class\|module`.
Draft of WebUI 2017-09-25 11:07:52 +00:00
Disable LocationStrategies if on electron/non-electron, README update 2018-07-16 08:28:45 +00:00			`### Build`
Draft of WebUI 2017-09-25 11:07:52 +00:00
Disable LocationStrategies if on electron/non-electron, README update 2018-07-16 08:28:45 +00:00			Run `yarn ng build` to build the project. The build artifacts will be stored in the `dist/` directory. Use the `-prod` flag for a production build.
Draft of WebUI 2017-09-25 11:07:52 +00:00
Disable LocationStrategies if on electron/non-electron, README update 2018-07-16 08:28:45 +00:00			`### Running unit tests`

			Run `yarn ng test` to execute the unit tests via [Karma](https://karma-runner.github.io).
Icons set Build electron for Linux, Windows and macOS. Ref. #18, #19, #20, #22 Include gns3server in electron app. Ref. #21 Bumping version Ref. #24 CD and Release for AppVeyor, CircleCi and TCI. Ref. #25, #26, #27, #28 Make lighter artifacts #31 Build gns3server for Linux, Windows and macOS. Ref. #33, #34, #35 2018-01-04 11:50:20 +00:00

Disable LocationStrategies if on electron/non-electron, README update 2018-07-16 08:28:45 +00:00			`## Releasing`
Icons set Build electron for Linux, Windows and macOS. Ref. #18, #19, #20, #22 Include gns3server in electron app. Ref. #21 Bumping version Ref. #24 CD and Release for AppVeyor, CircleCi and TCI. Ref. #25, #26, #27, #28 Make lighter artifacts #31 Build gns3server for Linux, Windows and macOS. Ref. #33, #34, #35 2018-01-04 11:50:20 +00:00
Release naming convention 2019-12-30 13:17:39 +00:00			`### Release naming convention`

			`Releases are named by the year and quarter when release is happening, e.g. January 2020 release is named 2020.1.X.`

Disable LocationStrategies if on electron/non-electron, README update 2018-07-16 08:28:45 +00:00			`### Bumping releases`
Icons set Build electron for Linux, Windows and macOS. Ref. #18, #19, #20, #22 Include gns3server in electron app. Ref. #21 Bumping version Ref. #24 CD and Release for AppVeyor, CircleCi and TCI. Ref. #25, #26, #27, #28 Make lighter artifacts #31 Build gns3server for Linux, Windows and macOS. Ref. #33, #34, #35 2018-01-04 11:50:20 +00:00
			`We're using [version-bump-prompt](https://www.npmjs.com/package/version-bump-prompt) for increasing version.`

Update README for using yarn 2018-03-26 10:04:28 +00:00			Install `version-bump-prompt` via:
Icons set Build electron for Linux, Windows and macOS. Ref. #18, #19, #20, #22 Include gns3server in electron app. Ref. #21 Bumping version Ref. #24 CD and Release for AppVeyor, CircleCi and TCI. Ref. #25, #26, #27, #28 Make lighter artifacts #31 Build gns3server for Linux, Windows and macOS. Ref. #33, #34, #35 2018-01-04 11:50:20 +00:00
			`npm install -g version-bump-prompt`

			`If you would like to bump prepatch just type:`

			`bump --prepatch --tag --push`

Disable LocationStrategies if on electron/non-electron, README update 2018-07-16 08:28:45 +00:00			`### Distribute release`
Icons set Build electron for Linux, Windows and macOS. Ref. #18, #19, #20, #22 Include gns3server in electron app. Ref. #21 Bumping version Ref. #24 CD and Release for AppVeyor, CircleCi and TCI. Ref. #25, #26, #27, #28 Make lighter artifacts #31 Build gns3server for Linux, Windows and macOS. Ref. #33, #34, #35 2018-01-04 11:50:20 +00:00
Update docs how to release WebUI 2019-07-03 10:14:19 +00:00			`We have got configured CircleCI, TravisCI and AppVeyor for distributing application for particular platform. In order to release you need to tag&push your changes from master.`
Icons set Build electron for Linux, Windows and macOS. Ref. #18, #19, #20, #22 Include gns3server in electron app. Ref. #21 Bumping version Ref. #24 CD and Release for AppVeyor, CircleCi and TCI. Ref. #25, #26, #27, #28 Make lighter artifacts #31 Build gns3server for Linux, Windows and macOS. Ref. #33, #34, #35 2018-01-04 11:50:20 +00:00
Update docs how to release WebUI 2019-07-03 10:14:19 +00:00			First of all please remove `dev` from version in `package.json` (for instance `2019.2.0-alpha.4dev` to `2019.2.0-alpha.4`). Commit & push changes with message `Release 2019.2.0-alpha.4` . Next step is to tag repository and push to origin:
Icons set Build electron for Linux, Windows and macOS. Ref. #18, #19, #20, #22 Include gns3server in electron app. Ref. #21 Bumping version Ref. #24 CD and Release for AppVeyor, CircleCi and TCI. Ref. #25, #26, #27, #28 Make lighter artifacts #31 Build gns3server for Linux, Windows and macOS. Ref. #33, #34, #35 2018-01-04 11:50:20 +00:00

Update docs how to release WebUI 2019-07-03 10:14:19 +00:00			`git tag v2019.2.0-alpha.4`
			`git push origin v2019.2.0-alpha.4`
Icons set Build electron for Linux, Windows and macOS. Ref. #18, #19, #20, #22 Include gns3server in electron app. Ref. #21 Bumping version Ref. #24 CD and Release for AppVeyor, CircleCi and TCI. Ref. #25, #26, #27, #28 Make lighter artifacts #31 Build gns3server for Linux, Windows and macOS. Ref. #33, #34, #35 2018-01-04 11:50:20 +00:00

			`When artifacts are made you can see draft release here: [gns3-web-ui releases](https://github.com/GNS3/gns3-web-ui/releases) which is waiting to be published.`
Add tag for relasing WebUI in gns3server 2019-07-03 10:16:30 +00:00			After release please change current version in `package.json` to `2019.2.0-alpha.5dev`'. Otherwise artifacts will be overwritten during the next commit. Don't forget to commit & push changes.
Update docs how to release WebUI 2019-07-03 10:14:19 +00:00
			`#### Updating gns3server`
Icons set Build electron for Linux, Windows and macOS. Ref. #18, #19, #20, #22 Include gns3server in electron app. Ref. #21 Bumping version Ref. #24 CD and Release for AppVeyor, CircleCi and TCI. Ref. #25, #26, #27, #28 Make lighter artifacts #31 Build gns3server for Linux, Windows and macOS. Ref. #33, #34, #35 2018-01-04 11:50:20 +00:00
Add tag for relasing WebUI in gns3server 2019-07-03 10:16:30 +00:00			Checkout the latest master of `gns3server`. Run command `./scripts/update-bundled-web-ui.sh --tag=v2019.2.0-alpha.5`. Commit & push changes with message `Release 2019.2.0-alpha.4`.
Icons set Build electron for Linux, Windows and macOS. Ref. #18, #19, #20, #22 Include gns3server in electron app. Ref. #21 Bumping version Ref. #24 CD and Release for AppVeyor, CircleCi and TCI. Ref. #25, #26, #27, #28 Make lighter artifacts #31 Build gns3server for Linux, Windows and macOS. Ref. #33, #34, #35 2018-01-04 11:50:20 +00:00
Disable LocationStrategies if on electron/non-electron, README update 2018-07-16 08:28:45 +00:00			`### Staging release`
Add to README how to upgrade package.json 2018-01-18 09:18:59 +00:00
Disable LocationStrategies if on electron/non-electron, README update 2018-07-16 08:28:45 +00:00			In case you would like to create a new staging release. Please create draft release on github, like `0.0.1-dev1`. After successful build you can find artifacts there.
Add to README how to upgrade package.json 2018-01-18 09:18:59 +00:00
Updating signing certificate in README 2019-01-08 13:11:09 +00:00			`### Updating signing certificate for Windows`

			Please follow this guide: [code-signing](https://www.electron.build/code-signing), use `certmgr.msc` exporting tool to limit the size of certificate.
Icons set Build electron for Linux, Windows and macOS. Ref. #18, #19, #20, #22 Include gns3server in electron app. Ref. #21 Bumping version Ref. #24 CD and Release for AppVeyor, CircleCi and TCI. Ref. #25, #26, #27, #28 Make lighter artifacts #31 Build gns3server for Linux, Windows and macOS. Ref. #33, #34, #35 2018-01-04 11:50:20 +00:00
Draft of WebUI 2017-09-25 11:07:52 +00:00			`## Further help`

			If you want to contribute to GNS3 Web UI feel free to reach us at `developers@gns3.net`.