mirror of
https://github.com/safing/portmaster
synced 2025-09-04 03:29:12 +00:00
104 lines
4.7 KiB
Markdown
104 lines
4.7 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
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](https://updates.safing.io/latest/linux_amd64/packages/portmaster-installer.deb). See the [Wiki](https://github.com/safing/portmaster/wiki/Linux) for more information.
|
|
|
|
Once the Portmaster is installed we need to add two new configuration flags. Execute the following:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
# 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](https://code.visualstudio.com/) (or it's oss or server-side variant) with
|
|
- the official [Angular Language Service](https://marketplace.visualstudio.com/items?itemName=Angular.ng-template) extension
|
|
- the [Tailwind CSS Extension Pack](https://marketplace.visualstudio.com/items?itemName=andrewmcodes.tailwindcss-extension-pack) extension
|
|
- the [formate: CSS/LESS/SCSS formatter](https://github.com/mblander/formate) 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](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](./src/app/environments/environment.ts).
|
|
|
|
### 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](https://karma-runner.github.io).
|
|
|
|
### Running end-to-end tests
|
|
|
|
Run `ng e2e` to execute the end-to-end tests via [Protractor](http://www.protractortest.org/).
|
|
|
|
### Further help
|
|
|
|
To get more help on the Angular CLI use `ng help` or go check out the [Angular CLI README](https://github.com/angular/angular-cli/blob/master/README.md).
|