This project was generated with Angular CLI version 10.2.0.
This is an attempt at making a self-service-first UI for Apache Traffic Control CDN architectures. The eventual goal is to slowly eat Traffic Portal by importing all of its functionality once the self-service UI is complete.
Traffic Portal runs on NodeJS version 13 (or later) and uses its built-in NPM package manager to manage dependencies.
To set up the Angular project for a production or testing environment
install all dependencies with npm install (pnpm is not supported with ngcc so it won't work)
# If you don't want the development dependencies, add `--production` # (only needs to be done once unless dependencies change) npm install
build and run the server-side (optional; production or production-like) and client-side modules.
E.g. running in server-side-rendering mode using the Angular CLI
# Add `--prod` for production deployment ng build # For production deployment, run ng run traffic-portal:server:production ng run traffic-portal:server # Runs the server locally at http://localhost:4000 node dist/server.js
E.g. running in server-side-rendering mode using NPM scripts
# These commands don't require a globally-available `@angular/cli` install, # but shadow intermediate steps (mostly those are also available as NPM # scripts, check out package.json to see them) # This builds for production deployment by default npm run build:ssr # Runs the server locally at http://localhost:4000 npm run serve:ssr
By default, the Traffic Portal server will attempt to connect to a Traffic Ops server running at the location specified by the TO_URL environment variable. If one is not set or you wish to override it, this (and other behavior) can be configured by passing arguments on the command line. To see the available command line options, pass the -h/--help flag to the server, e.g.
$ CMD="node dist/server.js" # The arguments can be passed to either command, use whichever you like $ CMD="npm run serve:ssr --" # (`--` signals the end of options to `npm`) $ $CMD --help # output is verbatim, but omits some things npm might echo e.g. the actual command usage: server.js [-h] [-v] [-t TRAFFIC_OPS] [-k] [-p PORT] [-c CERT_PATH -K KEY_PATH] [-C CONFIG_FILE] Traffic Portal re-written in modern Angular. Optional arguments: -h, --help Show this help message and exit. -v, --version Show program's version number and exit. -t TRAFFIC_OPS, --traffic-ops TRAFFIC_OPS Specify the Traffic Ops host/URL, including port. (Default: uses the `TO_URL` environment variable) -k, --insecure Skip Traffic Ops server certificate validation. This affects requests from Traffic Portal to Traffic Ops AND signature verification of any passed SSL -p PORT, --port PORT Specify the port on which Traffic Portal will listen (Default: 4200) -c CERT_PATH, --cert-path CERT_PATH Specify a location for an SSL certificate to be used by Traffic Portal. (Requires `-K`/`--key-path`. If both are omitted, will serve using HTTP) -K KEY_PATH, --key-path KEY_PATH Specify a location for an SSL certificate to be used by Traffic Portal. (Requires `-c`/`--cert-path`. If both are omitted, will serve using HTTP) -C CONFIG_FILE, --config-file CONFIG_FILE Specify a path to a configuration file - options are overridden by command-line flags. $
Because we need to proxy API requests back to Traffic Ops, running in debug mode is a bit more involved than it normally would be. Specifically, unless your Traffic Ops instance is listening at https://localhost:6443/ it'll require making a new file somewhere with the following information in JSON format:
{ "/api": { "target": "Traffic Ops server URL here - e.g. https://trafficops.apache.test", "secure": "This should be one of the literal boolean values 'true' or 'false' to indicate if certificate authenticity should be checked." } }
More documentation on the configuration options available in this file can be found in the relevant section of the angular-cli documentation. This step isn't necessary in a production deployment because the proxy is built into the server-side rendering server.
By default the file proxy.json in the project directory (i.e. the same one as this README.md file) will be used to define proxy settings, which causes it to expect a TO instance at https://localhost:6443 (CDN-in-a-Box's default Traffic Ops port). To change where this looks for a TO instance, make your own proxy configuration file and pass it in with --proxy-config /path/to/proxy.json.
# Using globally installed Angular CLI ## Using default proxy ng serve ## Using custom proxy settings ng serve --proxy-config /path/to/custom-proxy.json # using NPM scripts: ## Using default proxy npm start ## Using custom proxy settings npm start -- --proxy-config /path/to/custom-proxy.json
By default this will set up an Angular debug-mode server to run, listening on port 4200. Note that regardless of production-mode SSL configuration, this will only serve unencrypted HTTP responses by default. Also, unlike production mode which compiles things ahead of time, this will compile resources on-the-fly so that making changes to a file is immediately “live” without requiring the developer to restart the debug server.
This debugging mode server is NOT safe for production environments - not only does it not server HTTPS by default but the server itself is not audited for security flaws - use this for development and testing ONLY.
Coverage is pretty abysmal at the moment, but unit tests can be run using the Angular CLI. To run the unit tests, use the command ng test (dependencies must first be installed). This will attempt to open Chrome, Firefox and Opera, so ideally you would have those installed prior to running the tests.
End-to-end testing uses NightwatchJS and can be run by using ng e2e. More detailed instructions can be found in the nightwatch/ folder
Traffic Portal supports extending functionality through the use of Angular modules. The Custom module (located at src/app/custom/) contains the code to do so and any additional functionality should be added here as you would to any other Angular module. By default, this module is not built or included in the main bundle, to enable this modify the environment (src/environments) variable customModule to true.
This project uses eslint and an .editorconfig file for maintaining code style. If your editor doesn‘t support .editorconfig (VS Code does out-of-the-box as I understand, but Vim and Sublime Text need plugins) then you’ll want to manually configure it so as to avoid linting errors. There's quite a bit going on, but the big ones are:
These apply to all files:
These apply to Typescript, specifically
var - only const and let are allowedCode must pass linting to be accepted. To run the linter:
# Using Angular CLI ng lint # Using NPM scripts npm run lint
This UI is built to work with an API at version 3.0 in development mode (configured in ./src/environments/environment.ts) and 2.0 in production mode (configured in ./src/environments/environment.prod.ts). All endpoints will use this version by default, so when pointing it at a server that only supports e.g. a max of 1.5, you'll need to do edit the source file for your environment.
This UI obviously requires Javascript, but beyond that the hope is that any HTML5/CSS3/DOM3-compliant browser should work. Specifically, the ./.browserslistrc file defines our browser support, but in terms of browsers supported without regard for versioning, our aim is:
Internet Explorer and Safari are notably absent from this list. These browsers are standard-defying nightmares, and we refuse to support browsers that are end-of-life and/or do not recevie fixes for critical bugs.
The goal is to continuously support these browser in their latest and penultimate major release versions.
Run ng generate component component-name to generate a new component. You can also use ng generate directive|pipe|service|class|guard|interface|enum|module.
It may ask you to then specify a module, because it doesn‘t know if the thing you’re generating should be imported into the client-side code or the server-side code - nearly always the thing you're trying to do should be done on the client-side, so point it to the absolute or relative location of the src/app directory.
However, the files generated via this scaffolding will fail linting. Generally most of those errors can be fixed automatically with ng lint --fix (or equivalently npm run lint -- --fix), though.
To get more help on the Angular CLI use ng help or go check out the Angular CLI README.