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

docs(readme.md): small fixes

Browse source
This commit is contained in:
dec0dOS 2021-04-16 14:20:53 +03:00
parent fce118e23b
commit e27e19234f
1 changed files with 40 additions and 42 deletions
Download patch file Download diff file Expand all files Collapse all files

82
README.md
View file

@ -37,7 +37,6 @@
--- ---
## About ## About
<table> <table>
@ -45,12 +44,12 @@
<td> <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: 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:
* Full React-powered lightweight [SPA](https://en.wikipedia.org/wiki/Single-page_application) that brings better user experience, and ZeroUI is mobile-friendly.
* ZeroUI has ZeroTier Central complitible API. That means you could use CLI tools and custom applications made only for ZeroTier Central to manage your networks.
* ZeroUI implements controller-specific workarounds that address some existing [issues](https://github.com/zerotier/ZeroTierOne/issues/859)
* ZeroUI is more feature complete. ZeroUI has almost all network-controller supported features like rule editor. The development process hasn't stopped, so you will enjoy new features and bug fixes in the near future.
* ZeroUI deployment is simple. Please refer to [installation](#installation) for more info.
- Full React-powered lightweight [SPA](https://en.wikipedia.org/wiki/Single-page_application) that brings better user experience, and ZeroUI is mobile-friendly.
- ZeroUI has ZeroTier Central complitible API. That means you could use CLI tools and custom applications made only for ZeroTier Central to manage your networks.
- ZeroUI implements controller-specific workarounds that address some existing [issues](https://github.com/zerotier/ZeroTierOne/issues/859).
- ZeroUI is more feature complete. ZeroUI has almost all network-controller supported features like rule editor. The development process hasn't stopped, so you will enjoy new features and bug fixes in the near future.
- 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>Wait, I haven't heard about ZeroTier yet...</summary>
@ -60,36 +59,38 @@ This project is highly inspired by [ztncui](https://github.com/key-networks/ztnc
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. 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. To sum up, ZeroTier combines the capabilities of VPN and SD-WAN, simplifying network management.
</details> </details>
</td> </td>
</tr> </tr>
</table> </table>
### Built With ### Built With
Frontend: Frontend:
- [React](https://reactjs.org) - [React](https://reactjs.org)
- [Material UI](https://material-ui.com) - [Material UI](https://material-ui.com)
Backend: Backend:
- [NodeJS](https://nodejs.org) - [NodeJS](https://nodejs.org)
- [Express](https://expressjs.com) - [Express](https://expressjs.com)
- [Lowdb](https://github.com/typicode/lowdb) - [Lowdb](https://github.com/typicode/lowdb)
Deploy: Deploy:
- [Docker](https://www.docker.com) - [Docker](https://www.docker.com)
- [Docker Compose](https://docs.docker.com/compose/) - [Docker Compose](https://docs.docker.com/compose/)
- [Caddy](https://caddyserver.com) - [Caddy](https://caddyserver.com)
## Getting Started ## Getting Started
### Prerequisites ### Prerequisites
The recommended method to install ZeroUI is by using Docker and Docker Compose. The recommended method 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 from 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. For HTTPS setup you will need a domain name.
@ -115,37 +116,36 @@ The most simple one-minute installation. Great for the fresh VPS setup.
docker-compose logs docker-compose logs
``` ```
6. Disable your firewall for the following ports: `80/tcp`, `443/tcp` and `9993/udp` 6. 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 may use the old good 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
``` ```
7. Navigate to `https://YOURDOMAIN.com/app/`. 7. Navigate to `https://YOURDOMAIN.com/app/`.
Now you could use your ZeroUI instance with HTTPS support and automated certificate renewal. Now you could use your ZeroUI instance with HTTPS support and automated certificate renewal.
> To disable HTTPS, please remove https-proxy from `docker-compose.yml`, set `ZU_SECURE_HEADERS` to `false` and change zero-ui port `expose` to `ports`. > To disable HTTPS, please remove 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 |
| ---------------------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | ---------------------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| NODE_ENV | unset | You could learn more [here](https://nodejs.dev/learn/nodejs-the-difference-between-development-and-production) | | NODE_ENV | unset | You could learn more [here](https://nodejs.dev/learn/nodejs-the-difference-between-development-and-production) |
| ZU_SERVE_FRONTEND | true | You could disable frontend serving and use ZeroUI instance as REST API for your ZeroTier controller | | ZU_SERVE_FRONTEND | true | You could disable frontend serving and use ZeroUI instance as REST API for your ZeroTier controller |
| ZU_SECURE_HEADERS | true | Enables [helmet](https://helmetjs.github.io) | | ZU_SECURE_HEADERS | true | Enables [helmet](https://helmetjs.github.io) |
| ZU_CONTROLLER_ENDPOINT | http://localhost:9993/ | ZeroTier controller API endpoint | | ZU_CONTROLLER_ENDPOINT | http://localhost:9993/ | ZeroTier controller API endpoint |
| ZU_CONTROLLER_TOKEN | from /var/lib/zerotier-one/authtoken.secret | ZeroTier controller API token | | ZU_CONTROLLER_TOKEN | from /var/lib/zerotier-one/authtoken.secret | ZeroTier controller API token |
| ZU_DEFAULT_USERNAME | unset (docker-compose.yml: admin) | Default username that will be set on the first run | | ZU_DEFAULT_USERNAME | unset (docker-compose.yml: admin) | Default username that will be set on the first run |
| ZU_DEFAULT_PASSWORD | unset (docker-compose.yml: zero-ui) | Default password that will be set on the first run | | ZU_DEFAULT_PASSWORD | unset (docker-compose.yml: zero-ui) | Default password that will be set on the first run |
| ZU_DATAPATH | data/db.json | ZeroUI data storage path | | ZU_DATAPATH | data/db.json | ZeroUI data storage path |
ZeroUI could be deployed as a regular nodejs web application, but it requires ZeroTier controller that is installed with `zerotier-one` package. More info about the network controller you could read [here](https://github.com/zerotier/ZeroTierOne/tree/master/controller)
ZeroUI could be deployed as a regular nodejs web application, but it requires ZeroTier controller that is installed with `zerotier-one` package. More info about the network controller you could read [here](https://github.com/zerotier/ZeroTierOne/tree/master/controller).
## Usage ## Usage
@ -153,10 +153,11 @@ After installation, log in with your credentials that are declared with ZU_DEFAU
Currently, almost all actions are available through the UI. Refer to the [roadmap](#roadmap) for more information. Currently, almost all actions are available through the UI. Refer to the [roadmap](#roadmap) for more information.
_For the screenshots, please refer to the [screenshots](docs/SCREENSHOTS.md)_ _For the screenshots, please refer to the [screenshots](docs/SCREENSHOTS.md)._
### Update ### Update
To get the latest version just run
To get the latest version just run
docker-compose pull && docker-compose up -d --no-build docker-compose pull && docker-compose up -d --no-build
@ -172,17 +173,16 @@ You could also set up [watchtower](https://github.com/containrrr/watchtower) for
zu-main zu-controller zu-main zu-controller
### Backup ### Backup
The easiest way to create your ZeroUI data backup is to use the following commands: The easiest way to create your ZeroUI data backup is to use the following commands:
docker run --rm --volumes-from zu-controller -v $(pwd):/backup ubuntu tar cvf /backup/backup-controller.tar /var/lib/zerotier-one docker run --rm --volumes-from zu-controller -v $(pwd):/backup ubuntu tar cvf /backup/backup-controller.tar /var/lib/zerotier-one
docker run --rm --volumes-from zu-main -v $(pwd):/backup ubuntu tar cvf /backup/backup-ui.tar /app/backend/data docker run --rm --volumes-from zu-main -v $(pwd):/backup ubuntu tar cvf /backup/backup-ui.tar /app/backend/data
## Roadmap ## Roadmap
See the [open issues](https://github.com/dec0dOS/zero-ui/issues) for a list of proposed features (and known issues). See the [open issues](https://github.com/dec0dOS/zero-ui/issues) for a list of proposed features (and known issues).
## Contributing ## Contributing
Contributions are what makes 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**. Contributions are what makes 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**.
@ -194,6 +194,7 @@ Contributions are what makes the open-source community such an amazing place to
5. Open a pull request 5. Open a pull request
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.
Run `yarn commit` to open [TUI](https://en.wikipedia.org/wiki/Text-based_user_interface) that follows conventional commits guidelines.
### Development environment ### Development environment
@ -221,7 +222,7 @@ After you could start ZeroUI development environment:
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 [ZeroTier manual](https://www.zerotier.com/manual/#4)._
## Support ## Support
@ -230,21 +231,18 @@ Reach out to me at one of the following places:
- Telegram: ***REMOVED*** - Telegram: ***REMOVED***
- E-Mail: *****REMOVED***** - E-Mail: *****REMOVED*****
## Security ## Security
ZeroUI follows good practices of security, but 100% security can't be granted in software. ZeroUI is provided "as is" without any warranty. Use at your own risk. ZeroUI follows good practices of security, but 100% security can't be granted in software. 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, a more reliable and scalable solution, please use ZeroTier Central.
_For more info, please refer to the [security](docs/SECURITY.md)_ _For more info, please refer to the [security](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 or associated with or endorsed by ZeroTier Central or ZeroTier, Inc.
## License ## License
[![License: GPL v3](https://img.shields.io/badge/License-GPL%20v3-blue.svg?style=flat-square)](<https://tldrlegal.com/license/gnu-general-public-license-v3-(gpl-3)>) [![License: GPL v3](https://img.shields.io/badge/License-GPL%20v3-blue.svg?style=flat-square)](<https://tldrlegal.com/license/gnu-general-public-license-v3-(gpl-3)>)