github/zero-ui
1
0
Fork 0
mirror of https://github.com/dec0dOS/zero-ui.git synced 2025-07-06 21:11:41 -07:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: full update README

Browse source
This commit is contained in:
dec0dOS 2023-10-04 21:30:24 +01:00
parent 6ae44ed99c
commit a0a6997206
1 changed files with 61 additions and 74 deletions
Download patch file Download diff file Expand all files Collapse all files

135
README.md
View file

@ -43,34 +43,25 @@
## About ## About
<table> This project drew inspiration from [ztncui](https://github.com/key-networks/ztncui) and was developed to address the current limitations of self-hosted [network controllers](https://github.com/zerotier/ZeroTierOne/tree/master/controller). Some of the issues in [ztncui](https://github.com/key-networks/ztncui) cannot be resolved due to the core architecture of the project. ZeroUI aims to resolve these issues and introduces the following features:
<tr>
<td>
This project is highly inspired by [ztncui](https://github.com/key-networks/ztncui) and was developed to address the current limitations of applying the self-hosted [network controllers](https://github.com/zerotier/ZeroTierOne/tree/master/controller). Some [ztncui](https://github.com/key-networks/ztncui) problems cannot be fixed because of the core architecture of the project. ZeroUI tries to solve them and implements the following features: - It is a lightweight [Single Page Application (SPA)](https://en.wikipedia.org/wiki/Single-page_application) built with React, providing an improved user experience, and it is mobile-friendly.
- ZeroUI is compatible with the ZeroTier Central API, allowing you to use CLI tools and custom applications designed for ZeroTier Central to manage your networks.
- Full React-powered lightweight [SPA](https://en.wikipedia.org/wiki/Single-page_application) that brings a better user experience, and ZeroUI is mobile-friendly. - ZeroUI implements controller-specific workarounds to address certain existing [issues](https://github.com/zerotier/ZeroTierOne/issues/859) that are not addressed in ZTNCUI [issues](https://github.com/key-networks/ztncui/issues/63).
- ZeroUI has ZeroTier Central compatible API. That means you could use CLI tools and custom applications made only for ZeroTier Central to manage your networks. - ZeroUI is more feature-complete, supporting almost all network controller features, including a rule editor. Development is ongoing, so you can expect regular updates with new features and bug fixes.
- ZeroUI implements controller-specific workarounds that address some existing [issues](https://github.com/zerotier/ZeroTierOne/issues/859). ZTNCUI [does not](https://github.com/key-networks/ztncui/issues/63). - Deploying ZeroUI is straightforward; refer to the [installation](#installation) section for more information.
- ZeroUI is more feature complete. ZeroUI has almost all network-controller-supported features, for example, rule editor. The development process hasn't stopped, so you will enjoy new features and bug fixes shortly.
- ZeroUI deployment is simple. Please refer to [installation](#installation) for more info.
<details> <details>
<summary>Wait, I haven't heard about ZeroTier yet...</summary> <summary>Curious about ZeroTier?</summary>
<br> <br>
[ZeroTier](https://www.zerotier.com) is awesome [open source project](https://github.com/zerotier/ZeroTierOne) that is available on wide range of [platforms](https://www.zerotier.com/download/). [ZeroTier](https://www.zerotier.com) is an impressive [open-source project](https://github.com/zerotier/ZeroTierOne) available on a wide range of [platforms](https://www.zerotier.com/download/). It can resolve many of your complex networking issues, potentially replacing your intricate VPN setups. You can create a virtual LAN and manage all your devices effortlessly.
Most of your hard networking problems could be solved with ZeroTier. It could replace all your complex VPN setups. You can place all your devices on a virtual LAN and manage it easily.
To sum up, ZeroTier combines the capabilities of VPN and SD-WAN, simplifying network management. In essence, ZeroTier combines the capabilities of VPN and SD-WAN, simplifying network management.
</details> </details>
</td> ## Built With
</tr>
</table>
### Built With
Frontend: Frontend:
@ -83,7 +74,7 @@ Backend:
- [Express](https://expressjs.com) - [Express](https://expressjs.com)
- [Lowdb](https://github.com/typicode/lowdb) - [Lowdb](https://github.com/typicode/lowdb)
Ready to use deployment solution: Ready-to-use deployment solution:
- [Docker](https://www.docker.com) - [Docker](https://www.docker.com)
- [Docker Compose](https://docs.docker.com/compose/) - [Docker Compose](https://docs.docker.com/compose/)
@ -93,14 +84,13 @@ Ready to use deployment solution:
### Prerequisites ### Prerequisites
The recommended method to install ZeroUI is by using Docker and Docker Compose. The recommended way to install ZeroUI is by using Docker and Docker Compose. To install [Docker](https://docs.docker.com/get-docker) and [Docker Compose](https://docs.docker.com/compose/install) on your system, please follow the installation guide in the [official Docker documentation](https://docs.docker.com/get-docker).
To install [Docker](https://docs.docker.com/get-docker) and [Docker Compose](https://docs.docker.com/compose/install) on your system, please follow the installation guide from the [official Docker documentation](https://docs.docker.com/get-docker).
For HTTPS setup you will need a domain name. You can get it for free at https://www.duckdns.org. For HTTPS setup, you will need a domain name. You can obtain one for free at https://www.duckdns.org.
### Installation ### Installation
The most simple one-minute installation. Great for the fresh VPS setup. Here's a straightforward one-minute installation guide, perfect for a fresh VPS setup:
1. Create a project directory 1. Create a project directory
@ -140,28 +130,28 @@ docker-compose up -d --no-build
docker-compose logs -f docker-compose logs -f
``` ```
7. Disable your firewall for the following ports: `80/tcp`, `443/tcp` and `9993/udp` 7. Disable your firewall for the following ports: `80/tcp`, `443/tcp`, and `9993/udp`
- on Ubuntu/Debian with ufw installed: - On Ubuntu/Debian with ufw installed:
```sh ```sh
ufw allow 80/tcp ufw allow 80/tcp
ufw allow 443/tcp ufw allow 443/tcp
ufw allow 9993/udp ufw allow 9993/udp
``` ```
- or you may use the old good iptables: - Or you can use iptables:
```sh ```sh
iptables -A INPUT -p tcp --dport 80 -j ACCEPT iptables -A INPUT -p tcp --dport 80 -j ACCEPT
iptables -A INPUT -p tcp --dport 443 -j ACCEPT iptables -A INPUT -p tcp --dport 443 -j ACCEPT
iptables -A INPUT -p udp --dport 9993 -j ACCEPT iptables -A INPUT -p udp --dport 9993 -j ACCEPT
``` ```
8. Navigate to `https://YOURDOMAIN.com/app/`. 8. Navigate to `https://YOURDOMAIN.com/app/`.
Now you could use your ZeroUI instance with HTTPS support and automated certificate renewal. Now you can use your ZeroUI instance with HTTPS support and automated certificate renewal.
> To disable Caddy proxy and HTTPS, remove the `https-proxy` from `docker-compose.yml`, set `ZU_SECURE_HEADERS` to `false` and change zero-ui port `expose` to `ports`. > To disable Caddy proxy and HTTPS, remove the `https-proxy` from `docker-compose.yml`, set `ZU_SECURE_HEADERS` to `false`, and change zero-ui port `expose` to `ports`.
Advanced manual setups are also supported. Check the following environment variables as a reference: Advanced manual setups are also supported. Check the following environment variables as a reference:
| Name | Default value | Description | | Name | Default value | Description |
@ -181,51 +171,49 @@ Advanced manual setups are also supported. Check the following environment varia
ZeroUI could be deployed as a regular nodejs web application, but it requires a ZeroTier controller that is installed with the `zerotier-one` package. For more info about the network controller, you could read [here](https://github.com/zerotier/ZeroTierOne/tree/master/controller/#readme). ZeroUI could be deployed as a regular nodejs web application, but it requires a ZeroTier controller that is installed with the `zerotier-one` package. For more info about the network controller, you could read [here](https://github.com/zerotier/ZeroTierOne/tree/master/controller/#readme).
For Ansible Role, please refer to [zero-ui-ansible repo](https://github.com/dec0dOS/zero-ui-ansible). For Ansible Role, please refer to the [zero-ui-ansible repository](https://github.com/dec0dOS/zero-ui-ansible).
<details> <details>
<summary>Controller setup tips (outside the Docker)</summary> <summary>Controller Setup Tips (Outside Docker)</summary>
<br> <br>
If you are using the existing controller on the host, it may be necessary to allow connection from the Docker container. If you are using an existing controller on the host, you may need to allow connections from the Docker container. There are two ways to do this:
You could do it in two ways:
1. Allowing controller management from any IP address: 1. Allow controller management from any IP address:
```sh ```sh
echo "{\"settings\": {\"portMappingEnabled\": true,\"softwareUpdate\": \"disable\",\"allowManagementFrom\": [\"0.0.0.0/0\"]}}" > /var/lib/zerotier-one/local.conf echo "{\"settings\": {\"portMappingEnabled\": true,\"softwareUpdate\": \"disable\",\"allowManagementFrom\": [\"0.0.0.0/0\"]}}" > /var/lib/zerotier-one/local.conf
``` ```
> Warning: don't forget to block connections to 9993/TCP from WAN. Direct controller API does not mean to be exposed to WAN, it should be proxified via the ZeroUI backend. > Warning: Don't forget to block connections to 9993/TCP from the WAN. Directly exposing the controller API to the WAN is not recommended; it should be proxified via the ZeroUI backend.
2. Adding `network_mode: "host"` to zero-ui in docker-compose.yml. 2. Add `network_mode: "host"` to zero-ui in `docker-compose.yml`.
More info is provided in the following [discussion](https://github.com/dec0dOS/zero-ui/discussions/8). For more information, please refer to this [discussion](https://github.com/dec0dOS/zero-ui/discussions/8).
</details> </details>
## Usage ## Usage
After installation, log in with your credentials that are declared with ZU_DEFAULT_USERNAME and ZU_DEFAULT_PASSWORD. After installation, log in with the credentials declared with `ZU_DEFAULT_USERNAME` and `ZU_DEFAULT_PASSWORD`.
Currently, almost all main ZeroTier Central features are available. Refer to the [roadmap](#roadmap) for more information. Currently, almost all main ZeroTier Central features are available. Refer to the [roadmap](#roadmap) for more information.
_For the screenshots, please refer to the [screenshots](docs/SCREENSHOTS.md)._ _For screenshots, please refer to the [screenshots](docs/SCREENSHOTS.md) section._
### Update ### Update
To get the latest version just run To get the latest version, simply run
```sh ```sh
docker-compose pull && docker-compose up -d --no-build docker-compose pull && docker-compose up -d --no-build
``` ```
in the folder where `docker-compose.yml` is located. Backup is not required as your data is saved in Docker volumes but recommended. in the folder where `docker-compose.yml` is located. While backups are not required as your data is saved in Docker volumes, it is recommended.
### Backup ### Backup
You should regularly back up the `zerotier-one` and `data` folders in your ZeroUI installation directory. You should regularly back up the `zerotier-one` and `data` folders in your ZeroUI installation directory. You can do this manually before upgrading using the following commands:
You should do it manually before the upgrade via the following commands:
```sh ```sh
tar cvf backup-ui.tar data/ tar cvf backup-ui.tar data/
@ -234,7 +222,7 @@ tar cvf backup-zt.tar zerotier-one/
## Roadmap ## Roadmap
See the [open issues](https://github.com/dec0dOS/zero-ui/issues) for a list of proposed features (and known issues). For a list of proposed features (and known issues), see the [open issues](https://github.com/dec0dOS/zero-ui/issues).
- [Top Feature Requests](https://github.com/dec0dOS/zero-ui/issues?q=label%3Aenhancement+is%3Aopen+sort%3Areactions-%2B1-desc) (Add your votes using the 👍 reaction) - [Top Feature Requests](https://github.com/dec0dOS/zero-ui/issues?q=label%3Aenhancement+is%3Aopen+sort%3Areactions-%2B1-desc) (Add your votes using the 👍 reaction)
- [Top Bugs](https://github.com/dec0dOS/zero-ui/issues?q=is%3Aissue+is%3Aopen+label%3Abug+sort%3Areactions-%2B1-desc) (Add your votes using the 👍 reaction) - [Top Bugs](https://github.com/dec0dOS/zero-ui/issues?q=is%3Aissue+is%3Aopen+label%3Abug+sort%3Areactions-%2B1-desc) (Add your votes using the 👍 reaction)
@ -242,29 +230,30 @@ See the [open issues](https://github.com/dec0dOS/zero-ui/issues) for a list of p
[![GitHub issues open](https://img.shields.io/github/issues/dec0dOS/zero-ui.svg?maxAge=2592000)](https://github.com/dec0dOS/zero-ui/issues) [![GitHub issues open](https://img.shields.io/github/issues/dec0dOS/zero-ui.svg?maxAge=2592000)](https://github.com/dec0dOS/zero-ui/issues)
Please try to create bug reports that are: When creating bug reports, please ensure they are:
- _Reproducible._ Include steps to reproduce the problem. - _Reproducible._ Include steps to reproduce the problem.
- _Specific._ Include as much detail as possible: which version, what environment, etc. - _Specific._ Provide as much detail as possible, including version, environment, etc.
- _Unique._ Do not duplicate existing opened issues. - _Unique._ Avoid duplicating existing open issues.
- _Scoped to a Single Bug._ One bug per report. - _Scoped to a Single Bug._ Report one bug per issue.
## Contributing ## Contributing
First off, thanks for taking the time to contribute! Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make will benefit everybody else and are **greatly appreciated**. Firstly, thank you for considering contributing! Contributions are what make the open-source community thrive. Any contributions you make will benefit everyone, and they are highly appreciated.
1. Fork the project To contribute:
2. Create your feature branch (`git checkout -b feat/amazing_feature`)
3. Commit your changes (`git commit -m 'feat: add amazing_feature'`) 1. Fork the project.
4. Push to the branch (`git push origin feat/amazing_feature`) 2. Create your feature branch (`git checkout -b feat/amazing_feature`).
3. Commit your changes (`git commit -m 'feat: add amazing_feature'`).
4. Push to the branch (`git push origin feat/amazing_feature`).
5. [Open a Pull Request](https://github.com/dec0dOS/zero-ui/compare?expand=1) 5. [Open a Pull Request](https://github.com/dec0dOS/zero-ui/compare?expand=1)
ZeroUI uses [conventional commits](https://www.conventionalcommits.org), so please follow the guidelines. ZeroUI uses [conventional commits](https://www.conventionalcommits.org), so please follow the guidelines. You can use `yarn commit` to open a [Text-Based User Interface (TUI)](https://en.wikipedia.org/wiki/Text-based_user_interface) that follows conventional commits guidelines.
Run `yarn commit` to open [TUI](https://en.wikipedia.org/wiki/Text-based_user_interface) that follows conventional commits guidelines.
### Development environment ### Development Environment
To set up a development environment, please follow these steps: To set up a development environment, follow these steps:
1. Clone the repo 1. Clone the repo
@ -287,37 +276,35 @@ yarn dev
4. Navigate to http://localhost:3000 4. Navigate to http://localhost:3000
It is also required to install the ZeroTier controller. On Linux installing the `zerotier-one` package is enough, other platforms require some tweaking. Firstly you should get the controller token. On macOS, you could find it with the following command: You will also need to install the ZeroTier controller. On Linux, installing the `zerotier-one` package is sufficient, but other platforms may require some adjustments. First, you should obtain the controller token. On macOS, you can find it using the following command:
```sh ```sh
sudo cat "/Library/Application Support/ZeroTier/One/authtoken.secret" sudo cat "/Library/Application Support/ZeroTier/One/authtoken.secret"
``` ```
After you could start the ZeroUI development environment: Afterward, you can start the ZeroUI development environment:
```sh ```sh
ZU_CONTROLLER_TOKEN=TOKEN_FROM_authtoken.secret yarn dev ZU_CONTROLLER_TOKEN=TOKEN_FROM_authtoken.secret yarn dev
``` ```
_For other platforms, please refer to [ZeroTier manual](https://www.zerotier.com/manual/#4)._ For other platforms, please refer to the [ZeroTier manual](https://www.zerotier.com/manual/#4).
## Support ## Support
Reach out to me at one of the following places: If you need assistance or have questions, reach out through [GitHub Discussions](https://github.com/dec0dOS/zero-ui/discussions).
- [GitHub Discussions](https://github.com/dec0dOS/zero-ui/discussions)
## Security ## Security
ZeroUI follows good practices of security, but 100% security cannot be assured. ZeroUI is provided "as is" without any warranty. Use at your own risk. ZeroUI follows best practices for security, but complete security cannot be guaranteed. ZeroUI is provided "as is" without any warranty. Use at your own risk.
For enterprise support, a more reliable and scalable solution, please use ZeroTier Central. For enterprise support and a more reliable and scalable solution, please consider using ZeroTier Central.
_For more information and to report security issues, please refer to our [security documentation](docs/SECURITY.md)._ For more information and to report security issues, please refer to our [security documentation](docs/SECURITY.md).
## Copyright notice ## Copyright Notice
ZeroUI is not affiliated or associated with or endorsed by ZeroTier Central or ZeroTier, Inc. ZeroUI is not affiliated with, associated with, or endorsed by ZeroTier Central or ZeroTier, Inc.
## License ## License