diff --git a/README.md b/README.md index 9fc5fff..6ddbec8 100755 --- a/README.md +++ b/README.md @@ -43,34 +43,25 @@ ## About - - - - -
+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: -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 a better user experience, and ZeroUI is mobile-friendly. -- 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 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). -- 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. +- 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. +- 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 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. +- Deploying ZeroUI is straightforward; refer to the [installation](#installation) section for more information.
-Wait, I haven't heard about ZeroTier yet... +Curious about ZeroTier?
-[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/). -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. +[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. -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.
-
- -### Built With +## Built With Frontend: @@ -83,7 +74,7 @@ Backend: - [Express](https://expressjs.com) - [Lowdb](https://github.com/typicode/lowdb) -Ready to use deployment solution: +Ready-to-use deployment solution: - [Docker](https://www.docker.com) - [Docker Compose](https://docs.docker.com/compose/) @@ -93,14 +84,13 @@ Ready to use deployment solution: ### Prerequisites -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). +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). -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 -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 @@ -140,28 +130,28 @@ docker-compose up -d --no-build 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 - ufw allow 80/tcp - ufw allow 443/tcp - ufw allow 9993/udp +ufw allow 80/tcp +ufw allow 443/tcp +ufw allow 9993/udp ``` -- or you may use the old good iptables: +- Or you can use iptables: ```sh - iptables -A INPUT -p tcp --dport 80 -j ACCEPT - iptables -A INPUT -p tcp --dport 443 -j ACCEPT - iptables -A INPUT -p udp --dport 9993 -j ACCEPT +iptables -A INPUT -p tcp --dport 80 -j ACCEPT +iptables -A INPUT -p tcp --dport 443 -j ACCEPT +iptables -A INPUT -p udp --dport 9993 -j ACCEPT ``` 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: | 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). -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).
-Controller setup tips (outside the Docker) +Controller Setup Tips (Outside Docker)
-If you are using the existing controller on the host, it may be necessary to allow connection from the Docker container. -You could do it in two ways: +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: -1. Allowing controller management from any IP address: +1. Allow controller management from any IP address: ```sh 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).
## 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. -_For the screenshots, please refer to the [screenshots](docs/SCREENSHOTS.md)._ +_For screenshots, please refer to the [screenshots](docs/SCREENSHOTS.md) section._ ### Update -To get the latest version just run +To get the latest version, simply run ```sh 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 -You should regularly back up the `zerotier-one` and `data` folders in your ZeroUI installation directory. -You should do it manually before the upgrade via the following commands: +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: ```sh tar cvf backup-ui.tar data/ @@ -234,7 +222,7 @@ tar cvf backup-zt.tar zerotier-one/ ## 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 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) -Please try to create bug reports that are: +When creating bug reports, please ensure they are: - _Reproducible._ Include steps to reproduce the problem. -- _Specific._ Include as much detail as possible: which version, what environment, etc. -- _Unique._ Do not duplicate existing opened issues. -- _Scoped to a Single Bug._ One bug per report. +- _Specific._ Provide as much detail as possible, including version, environment, etc. +- _Unique._ Avoid duplicating existing open issues. +- _Scoped to a Single Bug._ Report one bug per issue. ## 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 -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`) +To contribute: + +1. Fork the project. +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) -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. +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. -### 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 @@ -287,37 +276,35 @@ yarn dev 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 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 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 -Reach out to me at one of the following places: - -- [GitHub Discussions](https://github.com/dec0dOS/zero-ui/discussions) +If you need assistance or have questions, reach out through [GitHub Discussions](https://github.com/dec0dOS/zero-ui/discussions). ## 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