diff --git a/.gitignore b/.gitignore index 09dd1f7..ee9edc3 100644 --- a/.gitignore +++ b/.gitignore @@ -2,10 +2,6 @@ .project .vagrant/ -meta.json -landr-dist -*.traineddata - /config /docker-compose.yml /package-lock.json diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 31aab32..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,30 +0,0 @@ -# Contributing to openbalena - -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. - -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]. - -[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 \ No newline at end of file diff --git a/README.md b/README.md index da4b1fd..b0b8e85 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,22 @@ -![logo](./docs/assets/openbalena-logo.svg) +openBalena -**openbalena is an open source platform to manage IoT and edge device fleets at scale.** +--- + +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. + +To learn more about openBalena, visit [balena.io/open][open-balena-website]. + + +## Features -## Highlights - **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 @@ -10,19 +24,15 @@ - **Powerful API & SDK**: Extend openBalena to fit your needs - **Built-in VPN**: Access your devices regardless of their network environment -## Motivation -openbalena is a platform that helps you 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 more. +## Getting Started -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. +Our [Getting Started guide][getting-started] is the most direct path to getting +an openBalena installation up and running and successfully deploying your +application to your device(s). -To learn more about openbalena, visit [balena.io/open][open-balena-website]. -### Setup and Configuration - -Our [Getting Started guide][getting-started] is the most direct path to getting an openbalena installation up and running and successfully deploying your application to your device(s). - -### Compatibility +## Compatibility The current release of openBalena has the following minimum version requirements: @@ -33,7 +43,8 @@ If you are updating from previous openBalena versions, ensure you update the bal CLI and reprovision any devices to at least the minimum required versions in order for them to be fully compatible with this release, as some features may not work. -### Documentation + +## Documentation While we're still working on the project documentation, please refer to the [balenaCloud documentation][documentation]. BalenaCloud is built on top of @@ -51,9 +62,68 @@ sections are of particular interest: - [Reference](https://balena.io/docs/reference) - [FAQ](https://balena.io/docs/faq/troubleshooting/faq) -### License -openbalena is licensed under the terms of AGPL v3. See [LICENSE](LICENSE) for details. +## 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. + + +## Contributing + +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. + +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]. + + +## Roadmap + +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: + +- Full documentation +- Full test suite +- Simplified deployment +- Remote host OS updates +- Support for custom device types + + +## Differences between openBalena and balenaCloud + +| openBalena | balenaCloud | +| ----- | ---- | +| Device updates using full images | Device updates using [delta images](https://www.balena.io/docs/learn/deploy/delta/) | +| Support for a single user | Support for [multiple users](https://www.balena.io/docs/learn/manage/account/#application-members) | +| Self-hosted deployment and scaling | balena-managed scaling and deployment | +| Community support via [forums][forums] | Private support on [paid plans](https://www.balena.io/pricing/) | +| Deploy via `balena deploy` only | Build remotely with native builders using [`balena push`](https://www.balena.io/docs/learn/deploy/deployment/#balena-push) or [`git push`](https://www.balena.io/docs/learn/deploy/deployment/#git-push) | +| No support for building via `git push` | Use the same CI workflow with [`git push`](https://www.balena.io/docs/learn/deploy/deployment/#git-push) | +| No public URL support | Serve websites directly from device with [public device URLs](https://www.balena.io/docs/learn/manage/actions/#enable-public-device-url) | +| Management via `balena-cli` only | Cloud-based device management dashboard | +| Download images from [balena.io][balena-os-website] | Download preconfigured images directly from the dashboard | +| No supported remote diagnostics | Remote device diagnostics | +| Supported devices: Raspberry Pi family, the Intel NUC, the NVIDIA Jetson TX2, and the balenaFin | All the devices listed in balena's [reference documentation](https://www.balena.io/docs/reference/hardware/devices/) | + +Additionally, refer back to the [roadmap](#roadmap) above for planned but not yet implemented features. + + +## 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 diff --git a/docs/01-getting-started.md b/docs/01-getting-started.md deleted file mode 100644 index ba75a84..0000000 --- a/docs/01-getting-started.md +++ /dev/null @@ -1,226 +0,0 @@ -# Getting started with openbalena - -This guide will walk you through the steps of deploying an openBalena server, -that together with the balena CLI, will enable you to create and manage a fleet -of devices running on your own infrastructure, on premises or in the cloud. The -openBalena servers must be reachable by the devices, which is easiest to achieve -with cloud providers like AWS, Google Cloud, Digital Ocean and others. - -This guide assumes a setup with two separate machines: - -- The openBalena _server_, running Linux. These instructions were tested with an - Ubuntu 18.04 x64 server. -- The _local machine_, running Linux, Windows or macOS where the balena CLI runs - (as a client to the openBalena server). The local machine should also have a - working installation of [Docker](https://docs.docker.com/get-docker/) so that - application images can be built and deployed to your devices, although it is - also possible to use balenaEngine on a balenaOS device instead of Docker. - -## Preparing a server for openBalena - -Login to the server via SSH and run the following commands. - -1. First, install or update essential software: - - ```bash - apt-get update && apt-get install -y build-essential git docker.io libssl-dev nodejs npm - ``` - -2. Install docker-compose: - - ```bash - curl -L https://github.com/docker/compose/releases/download/1.27.4/docker-compose-Linux-x86_64 -o /usr/local/bin/docker-compose - chmod +x /usr/local/bin/docker-compose - ``` - - Test your docker-compose installation with `$ docker-compose --version`. - -3. Create a new user, assign admin permissions and add to `docker` group: - - ```bash - adduser balena - usermod -aG sudo balena - usermod -aG docker balena - ``` - -### Install openBalena on the server - -1. On the server still, login as the new user and change into the home directory: - - ```bash - su balena - cd ~ - ``` - -2. Clone the openBalena repository and change into the new directory: - - ```bash - git clone https://github.com/balena-io/open-balena.git - cd open-balena/ - ``` - -3. Run the `quickstart` script as below. This will create a new `config` - directory and generate appropriate SSL certificates and configuration for the - server. The provided email and password will be used to automatically create - the user account for interacting with the server and will be needed later on - for logging in via the balena CLI. Replace the domain name for the `-d` - argument appropriately. - - ```bash - ./scripts/quickstart -U -P -d mydomain.com - ``` - - For more available options, see the script's help: - - ```bash - ./scripts/quickstart -h - ``` - -4. At this point, the openBalena server can be started with: - - ```bash - systemctl start docker - ./scripts/compose up -d - ``` - - The `-d` argument spawns the containers as background services. - -5. Tail the logs of the containers with: - - ```bash - ./scripts/compose exec journalctl -fn100 - ``` - - Replace `` with the name of any one of the services defined - in `compose/services.yml`; eg. `api` or `registry`. - -6. The server can be stopped with: - - ```bash - ./scripts/compose stop - ``` - -When updating openBalena to a new version, the steps are: - -```bash -./scripts/compose down -git pull -./scripts/compose build -./scripts/compose up -d -``` - -### Domain Configuration - -The following CNAME records must be configured to point to the openBalena server: - -```text -api.mydomain.com -registry.mydomain.com -vpn.mydomain.com -s3.mydomain.com -tunnel.mydomain.com -``` - -Check with your internet domain name registrar for instructions on how to -configure CNAME records. - -### Test the openBalena server - -To confirm that everything is running correctly, try a simple request from the -local machine to the server: - -```bash -curl -k https://api.mydomain.com/ping -OK -``` - -Congratulations! The openBalena server is up and running. The next step is to -setup the local machine to use the server, provision a device and deploy a -small project. - -## Install self-signed certificates on the local machine - -The installation of the openBalena server produces a few self-signed certificates -that must be installed on the local machine, so that it can securely communicate -with the server. - -The root certificate is found at `config/certs/root/ca.crt` on the server. Copy -it to some folder on the local machine and keep a note the path -- it will be -used later during the CLI installation. Follow the steps below for the specific -platform of the local machine. - -### Linux: - -```bash -sudo cp ca.crt /usr/local/share/ca-certificates/ca.crt -sudo update-ca-certificates -sudo systemctl restart docker -``` - -### macOS: - -```bash -sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ca.crt -osascript -e 'quit app "Docker"' && open -a Docker -``` - -### Windows: - -```bash -certutil -addstore -f "ROOT" ca.crt -``` - -The Docker daemon on the local machine must then be restarted for Docker to -pick up the new certificate. - -## Install the balena CLI on the local machine - -Follow the [balena CLI installation -instructions](https://github.com/balena-io/balena-cli/blob/master/INSTALL.md) -to install the balena CLI on the local machine. - -By default, the CLI targets the balenaCloud servers at `balena-cloud.com`, and -needs to be configured to target the openBalena server instead. Add the following -line to the CLI's configuration file, replacing `"mydomain.com"` with the domain -name of the openBalena server: - -```yaml -balenaUrl: 'mydomain.com' -``` - -The CLI configuration file can be found at: - -- On Linux or macOS: `~/.balenarc.yml` -- On Windows: `%UserProfile%\_balenarc.yml` - -If the file does not already exist, just create it. - -Wrapping up the CLI installation, set an environment variable that points to the -root certificate copied previously on the local machine. This step is to ensure -the CLI can securely interact with the openBalena server. - -| Shell | Command | -| ------------------ | ---------------------------------------------- | -| bash | `export NODE_EXTRA_CA_CERTS='/path/to/ca.crt'` | -| Windows cmd.exe | `set NODE_EXTRA_CA_CERTS=C:\path\to\ca.crt` | -| Windows PowerShell | `$Env:NODE_EXTRA_CA_CERTS="C:\path\to\ca.crt"` | - -## Deploy an application - -The commands below should be run on a terminal on the local machine (where the -balena CLI is installed). Ensure that the `NODE_EXTRA_CA_CERTS` environment -variable is set, as discussed above. - -### Login to openBalena - -Run `balena login`, select `Credentials` and use the email and password -specified during quickstart to login to the openBalena server. At any time, the -`balena whoami` command may be used to check which server the CLI is logged in to. - -## 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. \ No newline at end of file diff --git a/docs/02-deploy-an-application-or-fleet.md b/docs/02-deploy-an-application-or-fleet.md deleted file mode 100644 index 17afc6c..0000000 --- a/docs/02-deploy-an-application-or-fleet.md +++ /dev/null @@ -1,143 +0,0 @@ -# Deploy and provision an application - -The commands below should be run on a terminal on the local machine (where the -balena CLI is installed). Ensure that the `NODE_EXTRA_CA_CERTS` environment -variable is set, as discussed above. - -### Login to openBalena - -Run `balena login`, select `Credentials` and use the email and password -specified during quickstart to login to the openBalena server. At any time, the -`balena whoami` command may be used to check which server the CLI is logged in to. - -### Create an application - -Create a new application with `balena app create myApp`. Select the application's -default device type with the interactive prompt. The examples in this guide assume -a Raspberry Pi 3. - -An application contains devices that share the same architecture (such as ARM -or Intel i386), and also contains code releases that are deployed to the devices. -When a device is provisioned, it is added to an application, but can be migrated -to another application at any time. There is no limit to the number of applications -that can be created or to the number of devices that can be provisioned. - -At any time, the server can be queried for all the applications it knows about -with the following command: - -```bash -balena apps -ID APP NAME DEVICE TYPE ONLINE DEVICES DEVICE COUNT -1 myApp raspberrypi3 -``` - -### Provision a new device - -Once we have an application, it’s time to start provisioning devices. To do this, -first download a balenaOS image from [balena.io](https://balena.io/os/#download). -Pick the development image that is appropriate for your device. - -Unzip the downloaded image and use the balena CLI to configure it: - -```bash -balena os configure ~/Downloads/balena-cloud-raspberrypi3-2.58.3+rev1-dev-v11.14.0.img --app myApp -``` - -Flash the configured image to an SD card using [Etcher](https://balena.io/etcher). -Insert the SD card into the device and power it on. The device will register with -the openBalena server and after about two minutes will be inspectable: - -```bash -balena devices -ID UUID DEVICE NAME DEVICE TYPE APPLICATION NAME STATUS IS ONLINE SUPERVISOR VERSION OS VERSION -4 59d7700 winter-tree raspberrypi3 myApp Idle true 11.14.0 balenaOS 2.58.3+rev1 - -balena device 59d7700 -== WINTER TREE -ID: 4 -DEVICE TYPE: raspberrypi3 -STATUS: online -IS ONLINE: true -IP ADDRESS: 192.168.43.247 -APPLICATION NAME: myApp -UUID: 59d7700755ec5de06783eda8034c9d3d -SUPERVISOR VERSION: 11.14.0 -OS VERSION: balenaOS 2.58.3+rev1 -``` - -It's time to deploy code to the device. - -### Deploy a project - -Application release images are built on the local machine using the balena CLI. -Ensure the root certificate has been correctly installed on the local machine, -as discussed above. - -Let's create a trivial project that logs "Idling...". On an empty directory, -create a new file named `Dockerfile.template` with the following contents: - -```dockerfile -FROM balenalib/%%BALENA_MACHINE_NAME%%-alpine - -CMD [ "balena-idle" ] -``` - -Then build and deploy the project with: - -```bash -balena deploy myApp --logs -``` - -The project will have been successfully built when a friendly unicorn appears in -the terminal: - -```bash -[Info] Compose file detected -... -[Info] Creating release... -[Info] Pushing images to registry... -[Info] Saving release... -[Success] Deploy succeeded! -[Success] Release: f62a74c220b92949ec78761c74366046 - - \ - \ - \\ - \\ - >\/7 - _.-(6' \ - (=___._/` \ - ) \ | - / / | - / > / - j < _\ - _.-' : ``. - \ r=._\ `. - <`\\_ \ .`-. - \ r-7 `-. ._ ' . `\ - \`, `-.`7 7) ) - \/ \| \' / `-._ - || .' - \\ ( - >\ > - ,.-' >.' - <.'_.'' - <' -``` - -This command packages up the local directory, creates a new Docker image from -it and pushes it to the openBalena server. In turn, the server will deploy it to -all provisioned devices and within a couple of minutes, they will all run the -new release. Logs can be viewed with: - -```bash -balena logs 59d7700 --tail -[Logs] [10/28/2020, 11:40:16 AM] Supervisor starting -[Logs] [10/28/2020, 11:40:50 AM] Creating network 'default' -[Logs] [10/28/2020, 11:42:38 AM] Creating volume 'resin-data' -[Logs] [10/28/2020, 11:42:40 AM] Downloading image … -… -[Logs] [10/28/2020, 11:44:00 AM] [main] Idling... -``` - -Enjoy Balenafying All the Things! \ No newline at end of file diff --git a/docs/03-next-steps.md b/docs/03-next-steps.md deleted file mode 100644 index 91e3fb3..0000000 --- a/docs/03-next-steps.md +++ /dev/null @@ -1,14 +0,0 @@ -# Next steps - -- Try out [local mode](https://www.balena.io/docs/learn/develop/local-mode), - which allows you to build and sync code to your device locally for rapid - development. -- Develop an application with [multiple containers](https://www.balena.io/docs/learn/develop/multicontainer) - to provide a more modular approach to application management. -- Manage your device fleet with the use of [configuration](https://www.balena.io/docs/learn/manage/configuration/) - and [environment](https://www.balena.io/docs/learn/manage/serv-vars/) variables. -- Explore our [example projects](https://balena.io/blog/tags/etcher-featured/) - to give you an idea of more things you can do with balena. -- If you find yourself stuck or confused, help is just [a click away](https://www.balena.io/support). -- Pin selected devices to selected code releases using - [sample scripts](https://github.com/balena-io-examples/staged-releases). \ No newline at end of file diff --git a/docs/04-differences-openbalena-balenacloud.md b/docs/04-differences-openbalena-balenacloud.md deleted file mode 100644 index 5d8ed0b..0000000 --- a/docs/04-differences-openbalena-balenacloud.md +++ /dev/null @@ -1,17 +0,0 @@ -# Differences between openBalena and balenaCloud - -| openBalena | balenaCloud | -| ----- | ---- | -| Device updates using full images | Device updates using [delta images](https://www.balena.io/docs/learn/deploy/delta/) | -| Support for a single user | Support for [multiple users](https://www.balena.io/docs/learn/manage/account/#application-members) | -| Self-hosted deployment and scaling | balena-managed scaling and deployment | -| Community support via [forums][forums] | Private support on [paid plans](https://www.balena.io/pricing/) | -| Deploy via `balena deploy` only | Build remotely with native builders using [`balena push`](https://www.balena.io/docs/learn/deploy/deployment/#balena-push) or [`git push`](https://www.balena.io/docs/learn/deploy/deployment/#git-push) | -| No support for building via `git push` | Use the same CI workflow with [`git push`](https://www.balena.io/docs/learn/deploy/deployment/#git-push) | -| No public URL support | Serve websites directly from device with [public device URLs](https://www.balena.io/docs/learn/manage/actions/#enable-public-device-url) | -| Management via `balena-cli` only | Cloud-based device management dashboard | -| Download images from [balena.io][balena-os-website] | Download preconfigured images directly from the dashboard | -| No supported remote diagnostics | Remote device diagnostics | -| Supported devices: Raspberry Pi family, the Intel NUC, the NVIDIA Jetson TX2, and the balenaFin | All the devices listed in balena's [reference documentation](https://www.balena.io/docs/reference/hardware/devices/) | - -Additionally, refer back to the [roadmap](#roadmap) above for planned but not yet implemented features. \ No newline at end of file diff --git a/docs/05-roadmap.md b/docs/05-roadmap.md deleted file mode 100644 index 1386306..0000000 --- a/docs/05-roadmap.md +++ /dev/null @@ -1,13 +0,0 @@ -# openbalena roadmap - -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: - -- Full documentation -- Full test suite -- Simplified deployment -- Remote host OS updates -- Support for custom device types \ No newline at end of file diff --git a/docs/assets/balenaOS-components.png b/docs/assets/balenaOS-components.png deleted file mode 100644 index a4f4494..0000000 Binary files a/docs/assets/balenaOS-components.png and /dev/null differ diff --git a/docs/assets/balenaOS-read-only-rootfs.png b/docs/assets/balenaOS-read-only-rootfs.png deleted file mode 100644 index 3df0eba..0000000 Binary files a/docs/assets/balenaOS-read-only-rootfs.png and /dev/null differ diff --git a/docs/assets/image-partition-layout.png b/docs/assets/image-partition-layout.png deleted file mode 100644 index 857937b..0000000 Binary files a/docs/assets/image-partition-layout.png and /dev/null differ diff --git a/logo.png b/logo.png deleted file mode 100644 index 209ec80..0000000 Binary files a/logo.png and /dev/null differ