From c4a18f5bf8098adc41fc139ebad09135ec9bcd9f Mon Sep 17 00:00:00 2001 From: Andrew Nhem Date: Wed, 27 Apr 2022 14:17:57 -0700 Subject: [PATCH] add table workaround and docs edits --- CONTRIBUTING.md | 30 ++++++++++ README.md | 56 +------------------ docs/01-getting-started.md | 32 +++++++---- docs/04-differences-openbalena-balenacloud.md | 17 ++++++ docs/05-roadmap.md | 13 +++++ 5 files changed, 81 insertions(+), 67 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 docs/04-differences-openbalena-balenacloud.md create mode 100644 docs/05-roadmap.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..31aab32 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,30 @@ +# 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 58854ad..da4b1fd 100644 --- a/README.md +++ b/README.md @@ -51,63 +51,9 @@ sections are of particular interest: - [Reference](https://balena.io/docs/reference) - [FAQ](https://balena.io/docs/faq/troubleshooting/faq) - -### 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 - ### License -OpenBalena is licensed under the terms of AGPL v3. See [LICENSE](LICENSE) for details. - -### 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. +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 index c54aac5..ba75a84 100644 --- a/docs/01-getting-started.md +++ b/docs/01-getting-started.md @@ -16,7 +16,7 @@ This guide assumes a setup with two separate machines: 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 +## Preparing a server for openBalena Login to the server via SSH and run the following commands. @@ -43,7 +43,7 @@ Login to the server via SSH and run the following commands. usermod -aG docker balena ``` -#### Install openBalena on the server +### Install openBalena on the server 1. On the server still, login as the new user and change into the home directory: @@ -109,7 +109,7 @@ git pull ./scripts/compose up -d ``` -#### Domain Configuration +### Domain Configuration The following CNAME records must be configured to point to the openBalena server: @@ -124,7 +124,7 @@ tunnel.mydomain.com Check with your internet domain name registrar for instructions on how to configure CNAME records. -#### Test the openBalena server +### Test the openBalena server To confirm that everything is running correctly, try a simple request from the local machine to the server: @@ -138,7 +138,7 @@ 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 +## 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 @@ -149,7 +149,7 @@ 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: +### Linux: ```bash sudo cp ca.crt /usr/local/share/ca-certificates/ca.crt @@ -157,14 +157,14 @@ sudo update-ca-certificates sudo systemctl restart docker ``` -#### macOS: +### 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: +### Windows: ```bash certutil -addstore -f "ROOT" ca.crt @@ -173,7 +173,7 @@ 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 +## 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) @@ -205,14 +205,22 @@ the CLI can securely interact with the openBalena server. | 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 +## 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 +### 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. \ No newline at end of file +`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/04-differences-openbalena-balenacloud.md b/docs/04-differences-openbalena-balenacloud.md new file mode 100644 index 0000000..5d8ed0b --- /dev/null +++ b/docs/04-differences-openbalena-balenacloud.md @@ -0,0 +1,17 @@ +# 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 new file mode 100644 index 0000000..1386306 --- /dev/null +++ b/docs/05-roadmap.md @@ -0,0 +1,13 @@ +# 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