The Argus-frontend provides a graphical web interface to use with Argus. It has been built using React with TypeScript. The backend can be found at https://github.com/Uninett/Argus.
Here's how to get started with development.
Set up the Argus backend according to the instructions in its repository (https://github.com/Uninett/Argus).
Furthermore, Node.js is required. We also use the Node Package Manager (npm), which comes bundled with Node.js.
Optionally, you can forego a full installation of Node.js and npm on your local system, and instead opt to run a complete Argus setup using Docker Compose. If so, skip directly to the Install and startup section.
Installation procedures are as follows:
Use the Terminal app (located at /Applications/Utilities/Terminal.app
).
Install Homebrew with the following command.
ruby -e "$(curl -fsSL https://raw.github.com/Homebrew/homebrew/go/install)"
Then run
brew install node
to start the installation.
Open a terminal and run the following commands:
sudo apt-get install python-software-properties
sudo add-apt-repository ppa:chris-lea/node.js
sudo apt-get update
sudo apt-get install nodejs
Download the Node.js installer from http://nodejs.org/ and follow the installation instructions provided on the website.
Make sure that the git
command is available in your PATH.
After installation, test your Node.js with the following commands:
$ node --version
v10.11.0
$ npm --version
6.4.1
You successfully installed Node.js! Now let's continue to Argus frontend.
To download Argus frontend and install all required dependencies, run
git clone https://github.com/Uninett/Argus-frontend
cd Argus-frontend
npm install
Afterwards, use
npm start
to start the app in development mode. This will open your browser at http://localhost:3000 or similar.
Congrats, you now have the Argus frontend up and running!
Note that the website will automatically reload as you edit the code.
Default configuration options for the Argus frontend are located in src/config.tsx
. All of these options can be set using environment variables when running the frontend under the Node server (or in Docker Compose), or by providing configuration variables in runtime-config.json
file.
Configuration variables can be provided by adding a public/runtime-config.json
file when in development environment, or by serving a /runtime-config.json
file when in production environment. Example configuration file looks like this:
{
"backendUrl": "http://localhost:8000",
"enableWebsocketSupport": true,
"backendWSUrl": "ws://localhost:8000/ws",
"useSecureCookie": true,
"debug": true,
"cookieDomain": "localhost",
"defaultAutoRefreshInterval": 40,
"realtimeServiceMaxRetries": 7,
"use24hTime": true,
"timestampDateFormat": "yyyy-MM-dd",
"timestampTimeFormat": "HH:mm:ss",
"timestampTimeNoSeconds": "HH:mm",
"timestampTimezoneOffsetFormat": "xxx",
"timestampFormat": "{date} {time}{timezone_offset}",
"showSeverityLevels": true
}
Either provide environment variables when running the frontend under the Node server (or in Docker Compose), or add runtime-config.json
file with the configuration variables to the /public
folder.
Serve runtime-config.json
file with the configuration variables. It must be accessible as %YOUR_FRONTEND_BASE_URL%/runtime-config.json
.
Alternatively, you can configure the application via environment variables if using the production-oriented Docker image defined in ./docker/Dockerfile
. This image will automatically produce a runtime-config.json
from the environment variables exported to the container, as well as other variables provided in the ./docker/runtime-config-template.json
. Read more in the docker/README.md.
These environment variables are available:
true
to enable subscriptions to realtime incident updateshttps://argus-api.example.org/
, this value could be wss://argus-api.example.org/ws
.false
to disable the use of secure cookies. Typically only useful when deploying the development environment using non-TLS servers/regular HTTP.true
if you want debug output from the application.ARGUS_COOKIE_DOMAIN
variable on the backend.Configuration variables can be provided in runtime-config.json
file and will take precedence over the environment variables. These configuration variables are available:
true
to enable subscriptions to realtime incident updates.https://argus-api.example.org/
, this value could be wss://argus-api.example.org/ws
.true
if you want debug output from the application.true
if you want to enable filtering of incidents by severity levels.false
to disable the use of secure cookies. Typically only useful when deploying the development environment using non-TLS servers/regular HTTP.true
if you want time values to be displayed in 24-hours-day format.This repository contains a docker-compose.yml
definition to run all the backend components as services, while the Argus frontend runs directly off the checked out source code using npm. If you have Docker Compose on your system, run these commands to get everything up and running:
export UID
docker-compose up
(the export UID
step is to ensure the Argus frontend container runs using your system UID, so it doesn't produce root-owned files in the mounted source code directory).
Your Argus frontend should now be served on http://localhost:8080
, while your Argus API server should be served on http://localhost:8000
. As with running npm
locally, the website should automatically reload as you edit the code.
The default setup will install the latest version of the Argus API server from the master branch. If you need to customize which tag or branch to install, you can change the BRANCH
argument in docker-compose.yml
(or preferably implement your own docker-compose.override.yml
).
Given that Argus-frontend is installed and configured as described above, the following command can be used to run all the tests:
npm test
To run test files individually the following command can be used:
npm test -- nameOfTestFile
To run a single test and skip all the others, the following command can be used:
npm test -- -t "testName"
If you get the error message "React Native Error: ENOSPC: System limit for number of file watchers reached" (the code will still run, but tests might not), your version of React is probably not cleaning up its inotify watchers properly.
A temporary fix that always works is to reset the node_modules
directory:
rm -rf node_modules
npm install
.. but the error will eventually be back.
A permanent fix for some Linuxes is to increase the value of
fs.inotify.max_user_watches
in /etc/sysctl.conf
. It's a number that is
divisible by 540 on 32bit systems and 1024 on 64bit-systems. The max is
524288.
The folder structure of this project consists of components and views.
Each view component consists of other components.
App.js
handles the routing to each view component that is displayed on the web app.
We use prettier for JavaScript auto-formatting.
We recommend using an editor plugin to automatically format code on save, like prettier-atom or vim-prettier.
Another option to format the code is the yarn prettier
command.
Lint errors will be displayed on the console while the app is running.
The file ColorScheme.css
defines the colors used in the project.
Additionally, there is one CSS file for each component.
To install towncrier using pip
run
$ pip install towncrier
Alternatively you can also use pipx
and run
$ pipx install towncrier
Or for Ubuntu 22.04 LTS or later run
$ sudo apt-get update
$ sudo apt-get install towncrier
If it is not possible to install towncrier in the desired environment the files needed to later automatically generate the changelog from can also be created using the editor of one's choice as long as the naming conventions are followed.
To be able to automatically produce the changelog for a release one file for each
pull request (also called news fragment) needs to be added to the folder
changelog.d/
.
The name of the file consists of three parts separated by a period:
+
followed by a unique short description.security
, removed
, deprecated
, added
,
changed
and fixed
..md
, towncrier does not care which suffix a fragment has.So an example for a file name related to an issue/pull request would be 214.added.md
or for a file without corresponding issue +fixed-pagination-bug.fixed.md
.
This file can either be created manually with a file name as specified above and the changelog text as content or one can use towncrier to create such a file as following:
$ towncrier create -c "Changelog content" 214.added.md
When opening a pull request there will be a check to make sure that a news fragment is added and it will fail if it is missing.
To add all content from the changelog.d/
folder to the changelog file simply run
$ towncrier build --version {version}
This will also delete all files in changelog.d/
.
To preview what the addition to the changelog file would look like add the flag
--draft
. This will not delete any files or change CHANGELOG.md
. It will only output
the preview in the terminal.
A few other helpful flags:
date DATE
- set the date of the release, default is todaykeep
- do not delete the files in changelog.d/
More information about towncrier.