From 59c88fdce2295b848b01479060f2a44c48ce9a23 Mon Sep 17 00:00:00 2001 From: Julian Waller Date: Sat, 18 Nov 2023 13:57:34 +0100 Subject: [PATCH] chore: start porting docs --- docs/1_gettingstarted/choosing_a_pi.md | 9 +++++++ docs/1_gettingstarted/requirements.md | 7 +++++ docs/1_welcome.md | 1 + docs/2_using_the_image.md | 0 docs/2_using_the_image/securing_your_pi.md | 14 ++++++++++ docs/3_manual_install.md | 1 + docs/structure.json | 30 ++++++++++++++++++++++ 7 files changed, 62 insertions(+) create mode 100644 docs/1_gettingstarted/choosing_a_pi.md create mode 100644 docs/1_gettingstarted/requirements.md create mode 100644 docs/1_welcome.md create mode 100644 docs/2_using_the_image.md create mode 100644 docs/2_using_the_image/securing_your_pi.md create mode 100644 docs/3_manual_install.md create mode 100644 docs/structure.json diff --git a/docs/1_gettingstarted/choosing_a_pi.md b/docs/1_gettingstarted/choosing_a_pi.md new file mode 100644 index 0000000..c3f8fa3 --- /dev/null +++ b/docs/1_gettingstarted/choosing_a_pi.md @@ -0,0 +1,9 @@ +We only officialy support the Raspberry Pi 4 and 5, as well as derivatives of these such as the 400 or Compute Module 4. +It is possible to use the older models+, but **it is not recommended or supported**. Should you choose to do so, you do so at your own risk and with the understanding that the community will not be able to help you with any issues. + +The Raspberry Pi 4 is the first Raspberry Pi SBC (single board computer) that is able to stably run the Companion software. The 4GB/8GB variants of the Raspberry Pi 4/400/5 are the only recommended options. As stated above, any Raspberry Pi SBC lower than the 4 is unsupported and is used at your own risk. + +If you are installing Companion from scratch on an older Pi 4, make sure you've got your system updated with the latest eeprom/firmware updates ([info here](https://www.raspberrypi.org/forums/viewtopic.php?t=255001)). A update (late October 2019) combines the update mechanisms for both the SPI EEPROM and the VLI USB controller chip. Installing the latest updates will (in the future) open up the ability to boot your Raspberry Pi from a network-connected device or from an external USB storage device, and also updates the VLI firmware to reduce power consumption and bring running temperatures down by up to 3-4 °C. + + +Models older then the 4 are not supported as stability issues were identified which we believe are due to multiple (potentially interrelated) factors, including power output capability (e.g. to power a Stream Deck), power input requirements, OEM power supply capacity, Ethernet-no-longer-on-shared-USB-bus, maximum RAM, and of course CPU (as detailed in [Issue #313](https://github.com/bitfocus/companion/issues/313)). Accordingly, ongoing development efforts are focused on Raspberry Pi 4 systems. diff --git a/docs/1_gettingstarted/requirements.md b/docs/1_gettingstarted/requirements.md new file mode 100644 index 0000000..2072f88 --- /dev/null +++ b/docs/1_gettingstarted/requirements.md @@ -0,0 +1,7 @@ +We recommend a machine with 4GB or more of RAM. +If you are careful and use a limited number of connections you can go lower than this, but doing so can cause instability. + +You must use an x64 (Intel or AMD), or an ARM64 CPU and matching Linux distribution. +If using a Raspberry Pi or similar and installing yourself, make sure to use the ARM64 image instead of the default ARM image. + +We chose not to support the non 64bit ARM images, as they don't work as well for systems with over 4GB of memory, and many of our dependencies need extra work to compile for the ARM platform. It would take much more effort from us, and would result in there being two ARM versions (we would need to keep the ARM64 support) further increasing the work and confusion for users. diff --git a/docs/1_welcome.md b/docs/1_welcome.md new file mode 100644 index 0000000..9358484 --- /dev/null +++ b/docs/1_welcome.md @@ -0,0 +1 @@ +This lets you run Companion on a Raspberry Pi by providing a prebuilt image, or tooling which allows you to install Companion to the SBC (single board computer) or other linux machine of your choosing. \ No newline at end of file diff --git a/docs/2_using_the_image.md b/docs/2_using_the_image.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/2_using_the_image/securing_your_pi.md b/docs/2_using_the_image/securing_your_pi.md new file mode 100644 index 0000000..8c8a6f4 --- /dev/null +++ b/docs/2_using_the_image/securing_your_pi.md @@ -0,0 +1,14 @@ +Following the change in April 2022 by Raspberry Pi, the CompanionPi images do not allow ssh access until you setup a user. If you have a screen connected you will prompted to setup the user, or you can create the user with a config file at first boot + +To create the user at first boot: + * At the root of your SD card, create a file named `userconf.txt` + * Run `openssl passwd -6 ` to generate a hash of your password. + * Add a single line to the `userconf.txt` file, `:` using the output of the previous step as the password hash. + + +There are other security-oriented best practices that are recommended, such as: + +* Making sudo require a password +* Making sure you've got the latest os updates and security fixes +* Improving SSH security +* All of these recommended best practices can be found here, on the [raspberrypi.org website](https://www.raspberrypi.org/documentation/configuration/security.md) diff --git a/docs/3_manual_install.md b/docs/3_manual_install.md new file mode 100644 index 0000000..d08f7d2 --- /dev/null +++ b/docs/3_manual_install.md @@ -0,0 +1 @@ +This is supported on any x64 or ARM64 machine, and requires a debian or ubuntu based OS of a matching CPU architecture. diff --git a/docs/structure.json b/docs/structure.json new file mode 100644 index 0000000..0d4da7a --- /dev/null +++ b/docs/structure.json @@ -0,0 +1,30 @@ +[ + { + "label": "Getting started", + "file": "1_welcome.md", + "children": [ + { + "label": "System Requirements", + "file": "1_gettingstarted/requirements.md" + }, + { + "label": "Choosing a Pi", + "file": "1_gettingstarted/choosing_a_pi.md" + } + ] + }, + { + "label": "Using the Pi Image", + "file": "2_using_the_image.md", + "children": [ + + ] + }, + { + "label": "Manual Install", + "file": "3_manual_install.md", + "children": [ + + ] + } +] \ No newline at end of file