safing-portmaster/desktop/angular

Portmaster

Welcome to the new Portmaster User-Interface. It's based on Angular and is built, unit and e2e tested using @angular/cli.

Running locally

This section explains how to prepare your Ubuntu machine to build and test the new Portmaster User-Interface. It's recommended to use a virtual machine but running it on bare metal will work as well. You can use the new Portmaster UI as well as the old one in parallel so you can simply switch back when something is still missing or buggy.

1. Prepare your tooling

There's a simple dockerized way to build and test the new UI. Just make sure to have docker installed:

sudo apt update
sudo apt install -y docker.io git
sudo systemctl enable --now docker
sudo gpasswd -a $USER docker

2. Portmaster installation

Next, make sure to install the Portmaster using the official .deb installer from here. See the Wiki for more information.

Once the Portmaster is installed we need to add two new configuration flags. Execute the following:

echo 'PORTMASTER_ARGS="--experimental-nfqueue --devmode"' | sudo tee /etc/default/portmaster
sudo systemctl daemon-reload
sudo systemctl restart portmaster

3. Build and run the new UI

Now, clone this repository and execute the docker.sh script:

# Clone the repository
git clone https://github.com/safing/portmaster-ui

# Enter the repo and checkout the correct branch
cd portmaster-ui
git checkout feature/new-ui

# Enter the directory and run docker.sh
cd modules/portmaster
sudo bash ./docker.sh

Finally open your browser and point it to http://localhost:8080.

Hacking Quick Start

Although everything should work in the docker container as well, for the best development experience it's recommended to install @angular/cli locally.

It's highly recommended to:

• Use VSCode (or it's oss or server-side variant) with
  • the official Angular Language Service extension
  • the Tailwind CSS Extension Pack extension
  • the formate: CSS/LESS/SCSS formatter extension

Folder Structure

From the project root (the folder containing this README.md) there are only two folders with the following content and structure:

• src/ contains the actual application sources:
  • app/ contains the actual application sources (components, services, uni tests ...)
    • layout/ contains components that form the overall application layout. For example the navigation bar and the side dash are located there.
    • pages/ contains the different pages of the application. A page is something that is associated with a dedicated application route and is rendered at the applications main content.
    • services/ contains shared services (like PortAPI and friends)
    • shared/ contains shared components that are likely used accross other components or pages.
    • widgets/ contains widgets and their settings components for the application side dash.
    • debug/ contains a debug sidebar component
  • assets/ contains static assets that must be shipped seperately.
  • environments/ contains build and production related environment settings (those are handled by @angular/cli automatically, see angular.json)
• e2e/ contains end-to-end testing sources.

Development server

Run ng serve for a dev server. Navigate to http://localhost:4200/. The app will automatically reload if you change any of the source files.

In development mode (that is, you don't pass --prod) the UI expects portmaster running at ws://127.0.0.1:817/api/database/v1. See environment.

Code scaffolding

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.

Build

Run 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 ng test to execute the unit tests via Karma.

Running end-to-end tests

Run ng e2e to execute the end-to-end tests via Protractor.

Further help

To get more help on the Angular CLI use ng help or go check out the Angular CLI README.