ExternalVendorCode/open-balena
1
0
Fork 0
mirror of https://github.com/balena-io/open-balena.git synced 2024-12-18 21:27:52 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Update README

Browse Source 
Change-type: patch
This commit is contained in:
Akis Kesoglou 2018-11-12 18:02:49 +02:00
parent c426aa9453
commit 2e4064fab7
2 changed files with 98 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

131
README.md
View File

@ -1,64 +1,113 @@
<img alt="openBalena" src="docs/assets/openbalena-logo.svg" height="82">
## 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

8
docs/assets/openbalena-logo.svg Normal file
View File

@ -0,0 +1,8 @@
<svg xmlns="http://www.w3.org/2000/svg" width="228" height="42" viewBox="0 0 228 42">
<g fill="none" fill-rule="evenodd">
<path fill="#00D2EA" d="M57.231 23.086c0 2.186 1.667 3.8 3.635 3.8 1.968 0 3.635-1.614 3.635-3.828 0-2.213-1.667-3.826-3.635-3.826-1.968 0-3.635 1.613-3.635 3.826v.028zm-4.537-.055c0-3.69 2.651-8.035 8.172-8.035 5.521 0 8.172 4.346 8.172 8.062 0 3.718-2.65 8.063-8.172 8.063-5.52 0-8.172-4.345-8.172-8.063v-.027zM83.55 23.059c0-1.776-1.312-3.854-3.8-3.854-1.093 0-2.05.437-2.732 1.148-.657.684-1.067 1.667-1.067 2.76 0 1.067.41 2.023 1.094 2.706a3.82 3.82 0 0 0 2.706 1.12c2.378 0 3.799-1.94 3.799-3.853v-.027zm-11.944-7.57h4.264v1.666c.984-1.147 2.487-2.186 4.81-2.186 5.384 0 7.407 4.728 7.407 8.253 0 4.374-3.061 7.954-7.38 7.954-2.733 0-4.018-1.312-4.564-1.886v6.424h-4.537V15.488zM101.204 21.2c-.11-.71-1.038-2.405-3.389-2.405-2.35 0-3.28 1.695-3.389 2.405h6.778zm-6.833 3.444c.191 1.612 1.722 2.678 3.499 2.678 1.448 0 2.214-.628 2.76-1.42h4.647c-.738 1.694-1.804 3.006-3.088 3.88a7.373 7.373 0 0 1-4.32 1.367c-4.344 0-8.035-3.526-8.035-8.036 0-4.236 3.335-8.144 7.954-8.144 2.323 0 4.318.902 5.74 2.405 1.913 2.05 2.487 4.482 2.131 7.27H94.371zM108.31 15.488h4.235v1.613c.52-.738 1.476-2.132 4.182-2.132 5.111 0 5.63 4.154 5.63 6.204v9.484h-4.537v-8.282c0-1.667-.355-3.143-2.377-3.143-2.241 0-2.597 1.613-2.597 3.17v8.255h-4.537V15.488zM33.85 15.174v11.583c0 1.704-.918 3.29-2.395 4.139l-10.1 5.807c-.27.155-.55.277-.839.372v4.636c.49-.128.96-.312 1.396-.564l13.117-7.542a5.92 5.92 0 0 0 2.962-5.118V13.444c0-.512-.077-1.017-.213-1.513l-4.015 2.382c.054.281.087.568.087.86M2.955 8.323c-.515.297-.98.682-1.385 1.128l3.986 2.365c.29-.298.605-.57.974-.783L16.59 5.23a4.79 4.79 0 0 1 4.766-.003l10.1 5.808c.303.174.573.388.823.621l3.967-2.353c-.368-.377-.764-.717-1.216-.978L21.913.783a5.927 5.927 0 0 0-5.895.004L2.955 8.323zM16.588 36.7L6.53 30.898a4.787 4.787 0 0 1-2.39-4.136V15.17c0-.21.027-.417.056-.623L.163 12.154A5.72 5.72 0 0 0 0 13.437v15.056a5.918 5.918 0 0 0 2.955 5.114l13.063 7.537c.454.262.943.452 1.456.582v-4.643a4.517 4.517 0 0 1-.886-.382"/>
<g fill="#2A506F">
<path d="M132.219 20.286c-.995.804-1.492 1.83-1.492 3.077 0 1.32.458 2.426 1.372 3.321.915.895 2.118 1.342 3.609 1.342 1.411 0 2.554-.426 3.43-1.279.874-.85 1.311-1.912 1.311-3.181 0-1.25-.437-2.315-1.312-3.194-.875-.88-2.018-1.32-3.43-1.32-1.332.019-2.495.43-3.488 1.234zM127 11h3.966v6.588h.06c.437-.578 1.018-1.025 1.745-1.342a8.611 8.611 0 0 1 2.251-.637c.199-.018.387-.031.567-.04.178-.01.358-.014.536-.014 2.426 0 4.414.805 5.965 2.413 1.55 1.609 2.326 3.47 2.326 5.584 0 .308-.02.629-.06.963a5.71 5.71 0 0 1-.209.99 8.547 8.547 0 0 1-.716 1.898 7.322 7.322 0 0 1-1.132 1.626 7.133 7.133 0 0 1-2.714 1.857 9 9 0 0 1-3.34.638c-1.134 0-2.182-.196-3.147-.584-.965-.388-1.764-1.025-2.4-1.911l-.06-.027v2.033H127V11zM159.655 23.499c0-1.247-.443-2.3-1.328-3.16-.885-.858-2.033-1.278-3.444-1.26-1.452-.018-2.64.416-3.564 1.302-.924.886-1.386 1.988-1.386 3.307 0 1.23.481 2.264 1.446 3.104.964.84 2.112 1.253 3.444 1.234 1.432.019 2.595-.407 3.49-1.274.894-.868 1.342-1.943 1.342-3.226v-.027zm3.757 7.536h-3.638v-2.033h-.06c-.497.65-1.154 1.184-1.969 1.6a8.656 8.656 0 0 1-2.534.84l-.551.054c-.19.018-.374.027-.552.027-1.273 0-2.427-.222-3.46-.664a7.556 7.556 0 0 1-2.624-1.83 7.805 7.805 0 0 1-1.52-2.494 8.312 8.312 0 0 1-.538-2.983c0-1.048.164-2.014.492-2.9.329-.885.87-1.717 1.625-2.494.836-.886 1.764-1.541 2.789-1.966 1.024-.424 2.141-.637 3.355-.637 1.133 0 2.177.222 3.13.664a6.44 6.44 0 0 1 2.417 1.939v-2.142h3.638v15.019zM166.364 31.035h3.966V11h-3.966zM186.046 21.926c-.319-.886-.895-1.582-1.73-2.087a5.247 5.247 0 0 0-2.773-.76h-.24a5.695 5.695 0 0 0-2.683.847c-.835.51-1.391 1.176-1.67 2h9.096zm-9.036 3.2c.298.885.85 1.59 1.655 2.113a4.842 4.842 0 0 0 2.699.787c.755 0 1.465-.118 2.131-.352.666-.236 1.189-.552 1.567-.95l4.384-.027c-.498 1.356-1.506 2.5-3.027 3.43-1.521.93-3.157 1.396-4.906 1.396-2.406 0-4.458-.763-6.158-2.29-1.7-1.527-2.55-3.385-2.55-5.572 0-2.223.845-4.13 2.535-5.72 1.69-1.59 3.767-2.386 6.232-2.386 2.366 0 4.37.789 6.01 2.366 1.64 1.576 2.46 3.41 2.46 5.5 0 .235-.015.465-.045.69-.03.225-.065.446-.105.662-.02.073-.035.136-.044.19a.888.888 0 0 0-.015.162H177.01zM192.607 16.016h3.668V17.4h.06c.456-.56 1.058-.994 1.804-1.302a7.395 7.395 0 0 1 2.34-.542h.597c.079 0 .16.01.239.027a6.924 6.924 0 0 1 2.31.57c.747.325 1.388.75 1.924 1.273l.224.204c.07.063.134.14.194.23.635.814 1.014 1.682 1.133 2.603.12.922.18 1.862.18 2.82v7.753h-3.967v-7.781c0-.253-.01-.505-.03-.759a7.26 7.26 0 0 0-.21-1.152c-.099-.37-.248-.709-.446-1.017a2.753 2.753 0 0 0-1.06-.868 3.827 3.827 0 0 0-1.385-.379h-.373c-.07 0-.144.01-.224.027a3.904 3.904 0 0 0-1.342.421 2.63 2.63 0 0 0-1.014.88c-.198.29-.348.629-.447 1.018-.1.388-.16.781-.18 1.179-.02.235-.029.47-.029.705v7.726h-3.966V16.016zM223.472 23.499c0-1.247-.443-2.3-1.327-3.16-.885-.858-2.034-1.278-3.444-1.26-1.453-.018-2.64.416-3.564 1.302-.924.886-1.388 1.988-1.388 3.307 0 1.23.483 2.264 1.447 3.104.964.84 2.113 1.253 3.445 1.234 1.431.019 2.594-.407 3.489-1.274.894-.868 1.342-1.943 1.342-3.226v-.027zm3.758 7.536h-3.64v-2.033h-.058c-.498.65-1.154 1.184-1.969 1.6a8.666 8.666 0 0 1-2.535.84l-.551.054c-.19.018-.373.027-.552.027-1.272 0-2.426-.222-3.46-.664a7.548 7.548 0 0 1-2.623-1.83 7.796 7.796 0 0 1-1.521-2.494 8.312 8.312 0 0 1-.538-2.983c0-1.048.165-2.014.492-2.9.33-.885.87-1.717 1.626-2.494.835-.886 1.764-1.541 2.788-1.966 1.024-.424 2.142-.637 3.355-.637 1.133 0 2.177.222 3.131.664a6.44 6.44 0 0 1 2.416 1.939v-2.142h3.639v15.019z"/>
</g>
</g>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 5.5 KiB