From 2e4064fab706eb5334c82018ff32ff6f7e2ab678 Mon Sep 17 00:00:00 2001 From: Akis Kesoglou Date: Mon, 12 Nov 2018 18:02:49 +0200 Subject: [PATCH] Update README Change-type: patch --- README.md | 131 ++++++++++++++++++++++---------- docs/assets/openbalena-logo.svg | 8 ++ 2 files changed, 98 insertions(+), 41 deletions(-) create mode 100644 docs/assets/openbalena-logo.svg diff --git a/README.md b/README.md index 355e09b..92390a0 100644 --- a/README.md +++ b/README.md @@ -1,64 +1,113 @@ +openBalena -## Host requirements +--- -- Docker >= 18.05.0 -- Docker Compose >= 1.11 -- OpenSSL >= 1.0.0 -- Python >= 2.7 or >=3.4 -- NodeJS >= 4.0 +OpenBalena is a platform to deploy and manage connected devices. Devices run +[balenaOS][balena-os-website], a host operating system designed for running +containers on IoT devices, and are managed via the [balena CLI][balena-cli], +which you can use to configure your application containers, push updates, check +status, view logs, and so forth. OpenBalena’s backend services, composed of +battle-tested components that we’ve run in production on [balenaCloud][balena-cloud-website] +for years, can store device information securely and reliably, allow remote +management via a built-in VPN service, and efficiently distribute container +images to your devices. -## Installation +To learn more about openBalena, visit [balena.io/open][open-balena-website]. -Make sure you have the software listed above installed. -In a terminal, clone the project with: +## Features - $ git clone https://github.com/balena-io/open-balena.git +- **Simple provisioning**: Adding devices to your fleet is a breeze +- **Easy updates**: Remotely update the software on your devices with a single command +- **Container-based**: Benefit from the power of virtualization, optimized for the edge +- **Scalable**: Deploy and manage one device, or one million +- **Powerful API & SDK**: Extend openBalena to fit your needs +- **Built-in VPN**: Access your devices regardless of their network environment -Change into the `open-balena` directory and run the configuration script. -This will create a new directory, `config`, and generate appropriate SSL -certificates and configuration for the instance. - $ ./scripts/quickstart +## Roadmap -You may optionally configure the instance to run under a custom domain name. -The default is `openbalena.local`. For example: +OpenBalena is currently in beta. While fully functional, it lacks features we +consider important before we can comfortably call it production-ready. During +this phase, don’t be alarmed if things don’t work as expected just yet (and +please let us know about any bugs or errors you encounter!). The following +improvements and new functionality is planned: - $ ./scripts/quickstart -d mydomain.com +- Full documentation +- Full test suite +- Simplified deployment +- Remote host OS updates +- Support for custom device types -For more available options, see the script's help: - $ ./scripts/quickstart -h +## Contributing -Start the instance with: +Everyone is welcome to contribute to openBalena. There are many different ways +to get involved apart from submitting pull requests, including helping other +users on the [forums][forums], reporting or triaging [issues][issue-tracker], +reviewing and discussing [pull requests][pulls], or just spreading the word. - $ ./scripts/compose up -d +All of openBalena is hosted on GitHub. Apart from its constituent components, +which are the [API][open-balena-api], [VPN][open-balena-vpn], [Registry][open-balena-registry], +[S3 storage service][open-balena-s3], and [Database][open-balena-db], contributions +are also welcome to its client-side software such as the [balena CLI][balena-cli], +the [balena SDK][balena-sdk], [balenaOS][balena-os] and [balenaEngine][balena-engine]. -Stop the instance with: - $ ./scripts/compose stop +## Getting Started -To remove all traces of the instance, run the following commands and finally -delete the configuration folder. +Our [Getting Started][getting-started] guide is the most direct path to getting +an openBalena installation up and running and successfully deploying your +application to your device(s). -**WARNING**: This will remove *all* data. - $ ./scripts/compose kill - $ ./scripts/compose down - $ docker volume rm openbalena_s3 openbalena_redis openbalena_db openbalena_registry +## Documentation -### macOS & Windows +While we're still working on the project documentation, please refer to the +[balenaCloud documentation][documentation]. BalenaCloud is built on top of +openBalena, so the core concepts and functionality is identical. The following +sections are of particular interest: -On macOS and Windows you need Vagrant. `open-balena` is not being tested with -docker-machine. `open-balena` comes with an appropriate `Vagrantfile` for -setting up the VM, installing dependencies and starting the platform. +- [Overview / A balena primer](https://balena.io/docs/learn/welcome/primer) +- [Overview / Core Concepts](https://balena.io/docs/learn/welcome/concepts) +- [Overview / Going to production](https://balena.io/docs/learn/welcome/production-plan) +- [Develop / Define a container](https://balena.io/docs/learn/develop/dockerfile) +- [Develop / Multiple containers](https://balena.io/docs/learn/develop/multicontainer) +- [Develop / Runtime](https://balena.io/docs/learn/develop/runtime) +- [Develop / Interact with hardware](https://balena.io/docs/learn/develop/hardware) +- [Deploy / Optimize your builds](https://balena.io/docs/learn/deploy/build-optimization) +- [Reference](https://balena.io/docs/reference) +- [FAQ](https://balena.io/docs/faq/troubleshooting/faq) -- Install Vagrant >= 2.0 -- `$ vagrant plugin install vagrant-docker-compose` -- `$ vagrant up` -When provisioning completes and the VM has started, `open-balena` services -should be running inside the VM. You will need to expose these services to -the outside in order for them to be reachable by devices. To do so, you must -setup DNS for the domain name you've deployed the instance as to point to the -VM's IP address. +## Getting Help + +You are welcome to submit any questions, participate in discussions and request +help with any issue in [openBalena forums][forums]. The balena team frequents +these forums and will be happy to help. You can also ask other community members +for help, or contribute by answering questions posted by fellow openBalena users. +Please do not use the issue tracker for support-related questions. + + +## License + +OpenBalena is licensed under the terms of AGPL v3. See [LICENSE](LICENSE) for details. + + +[balena-cli]: https://github.com/balena-io/balena-cli +[balena-cloud-website]: https://balena.io/cloud +[balena-engine]: https://github.com/balena-os/balena-engine +[balena-os-website]: https://balena.io/os +[balena-os]: https://github.com/balena-os/meta-balena +[balena-sdk]: https://github.com/balena-io/balena-sdk +[documentation]: https://balena.io/docs/learn/welcome/introduction/ +[forums]: https://forums.balena.io/c/open-balena +[getting-started]: https://balena.io/open/docs/getting-started +[issue-tracker]: https://github.com/balena-io/open-balena/issues +[open-balena-api]: https://github.com/balena-io/open-balena-api +[open-balena-db]: https://github.com/balena-io/open-balena-db +[open-balena-registry]: https://github.com/balena-io/open-balena-registry +[open-balena-s3]: https://github.com/balena-io/open-balena-s3 +[open-balena-vpn]: https://github.com/balena-io/open-balena-vpn +[open-balena-website]: https://balena.io/open +[pulls]: https://github.com/balena-io/open-balena/pulls diff --git a/docs/assets/openbalena-logo.svg b/docs/assets/openbalena-logo.svg new file mode 100644 index 0000000..82a0305 --- /dev/null +++ b/docs/assets/openbalena-logo.svg @@ -0,0 +1,8 @@ + + + + + + + +