diff --git a/download_and_install/_ola_on_windows_msys2.md b/download_and_install/_ola_on_windows_msys2.md new file mode 100644 index 0000000..5ffc744 --- /dev/null +++ b/download_and_install/_ola_on_windows_msys2.md @@ -0,0 +1,105 @@ +OLA on Windows +============== + +TODO: This doesn't compile + +OLA is partially available on Windows using MSYS2. Please note that not all plugins are functional on Windows - only the +following are available: + +- ArtNet +- Dummy +- ESP Net +- FTDI +- KiNet +- OSC +- Pathport +- SandNet +- Strand Shownet +- USB DMX + +For other uses, consider using a Linux system, such as a [Raspberry Pi](ola_on_raspberry_pi). + +These instructions are generally similar to [compiling from source](compiling_from_source) on a Linux system, but are +adapted slightly to the peculiarities of Windows. The troubleshooting advice there is applicable here as well. + +Setup +===== + +Start by downloading and installing [MSYS2](https://www.msys2.org/). *Be sure to follow their instructions all the way +through, including performing updates.* + +MSYS2 installs a subsystem on your machine. This means it functions a bit differently than the standard Windows command +prompt. In particular: + +- Copy is Ctrl + Insert. +- Paste is Shift + Insert. +- The directory separator is a forward slash (`/`). +- Directories appear differently than they do in Windows. The root is `/`; all directories descend from `/`. + See [here](https://www.msys2.org/wiki/MSYS2-introduction/#file-system) for how MSYS2 maps your Windows drives + and directories into this hierarchy. Your Windows "Documents" folder, unless you've moved it inside Windows, is likely + at `/c/Users//Documents`. + +To install dependencies, launch "MSYS2 MSYS" from the Start Menu (it may have opened automatically after installation): + + pacman -S \ + base-devel \ + git \ + libutil-linux-devel \ + mingw-w64-x86_64-cppunit \ + mingw-w64-x86_64-libftdi \ + mingw-w64-x86_64-liblo \ + mingw-w64-x86_64-libmicrohttpd \ + mingw-w64-x86_64-libusb \ + mingw-w64-x86_64-protobuf \ + mingw-w64-x86_64-python \ + mingw-w64-x86_64-python-numpy \ + mingw-w64-x86_64-python-protobuf \ + mingw-w64-x86_64-toolchain + +When asked which members to install, press enter to install all. This process will take quite some time. + +If you're using USB devices, use [Zadig](https://zadig.akeo.ie/) to install the libusbK for each FTDI device. + +Run the below command to tell the build system where to find the newly-installed packages: + + echo "export PKG_CONFIG_PATH=/usr/lib/pkgconfig:${PKG_CONFIG_PATH}" >> ~/.bashrc + +Now close the MSYS2 window. + +Build +===== + +From the Start Menu, launch "MSYS2 MinGW 64-bit". + +Navigate to the directory you wish to use to build OLA. +Run `git clone https://github.com/OpenLightingProject/ola.git && cd ola`. + +If this is the first time compiling with this download, generate the build system: + + autoreconf -i + +OLA uses autotools for building. Run `./configure --help` to see all options. + +To install with all available Windows plugins, run: + + ./configure \ + --enable-python-libs \ + --disable-all-plugins \ + --enable-artnet \ + --enable-dummy \ + --enable-espnet \ + --enable-ftdidmx \ + --enable-kinet \ + --enable-osc \ + --enable-pathport \ + --enable-sandnet \ + --enable-shownet \ + --enable-usbdmx + +To build OLA after configuring, run: + + make -j$(nproc) + make check + make install + +TODO: Usage diff --git a/download_and_install/_ola_on_windows_wsl.md b/download_and_install/_ola_on_windows_wsl.md new file mode 100644 index 0000000..4568d4a --- /dev/null +++ b/download_and_install/_ola_on_windows_wsl.md @@ -0,0 +1,120 @@ +OLA on Windows +============== + +OLA is not presently available directly on Windows. However, it can be used with a shim. Note these installations are +not well-tested and may encounter problems. In particular, non-network plugins (e.g. USB DMX) will fail to function. For +show-critical uses, consider using a Linux system, such as a [Raspberry Pi](ola_on_raspberry_pi). + +Windows Subsystem for Linux (WSL) allows running programs written for Linux (such as OLA) on Windows. WSL requires +Windows 10 version 1903 or newer. See Microsoft's notes on Windows +versions [here](https://docs.microsoft.com/en-us/windows/wsl/install-win10#step-2---check-requirements-for-running-wsl-2). + +Setup +===== + +1. Begin by installing WSL using the + [installation instructions](https://docs.microsoft.com/en-us/windows/wsl/install-win10). Be sure to follow the + instructions for WSL2, not WSL1 +2. WSL supports several distributions, but OLA is best supported with Debian. Install the + [Debian WSL distribution](https://www.microsoft.com/en-us/p/debian/9msvkqc78pk6) from the Microsoft Store. +3. From the Start Menu, launch Debian. Create a UNIX username and password when prompted. +4. Once the system is installed, run `sudo apt-get update` and `sudo apt-get upgrade` to keep the system updated. +5. Install OLA with `sudo apt-get install ola`. + +Networking +========== + +TODO: This doesn't forward UDP ports, a function required for nearly everything interesting you can do with OLA. + +WSL uses a virtual network adapter internally. This means connections to OLA from your LAN will initially fail. There is +some work being done in this area [here](https://github.com/microsoft/WSL/issues/4150). The following instructions are +adapted from a [workaround](https://github.com/microsoft/WSL/issues/4150#issuecomment-504209723) in that issue. + +Create a PowerShell script somewhere on your system with these contents: + + $remoteip = wsl -d Debian ip addr `| grep -Ee 'inet.*eth0' + $found = $remoteip -match '\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}'; + + if( $found ){ + $remoteip = $matches[0]; + } else{ + Write-Output "The Script Exited, the ip address of WSL 2 cannot be found"; + exit; + } + + #[Ports] + # ADD PORTS HERE: all the ports you want to forward separated by comma + $ports=@(9090, 9099); + + #[Static ip] + # You can change the addr to your ip config to listen to a specific address + $addr='0.0.0.0'; + $ports_a = $ports -join ","; + + # Remove Firewall Exception Rules + Invoke-Expression "Remove-NetFireWallRule -DisplayName 'WSL 2 Firewall Unlock (TCP)'"; + Invoke-Expression "Remove-NetFireWallRule -DisplayName 'WSL 2 Firewall Unlock (UDP)'"; + + # Adding exceptions for inbound and outbound traffic + Invoke-Expression "New-NetFireWallRule -DisplayName 'WSL 2 Firewall Unlock (TCP)' -Direction Outbound -LocalPort $ports_a -Action Allow -Protocol TCP"; + Invoke-Expression "New-NetFireWallRule -DisplayName 'WSL 2 Firewall Unlock (UDP)' -Direction Outbound -LocalPort $ports_a -Action Allow -Protocol UDP"; + Invoke-Expression "New-NetFireWallRule -DisplayName 'WSL 2 Firewall Unlock (TCP)' -Direction Inbound -LocalPort $ports_a -Action Allow -Protocol TCP"; + Invoke-Expression "New-NetFireWallRule -DisplayName 'WSL 2 Firewall Unlock (UDP)' -Direction Inbound -LocalPort $ports_a -Action Allow -Protocol UDP"; + + for( $i = 0; $i -lt $ports.length; $i++ ){ + $port = $ports[$i]; + Invoke-Expression "netsh interface portproxy delete v4tov4 listenport=$port listenaddress=$addr"; + Invoke-Expression "netsh interface portproxy add v4tov4 listenport=$port listenaddress=$addr connectport=$port connectaddress=$remoteip"; + } + +Add additional ports, if needed, separated by a comma below `# ADD PORTS HERE`. + +Next, open the Task Scheduler. Create a new task: + +![](images/wsl_networking_1.png) + +Configure the task like so: + +![](images/wsl_networking_2.png) + +In the triggers tab, add a new trigger: + +![](images/wsl_networking_3.png) + +In the actions tab, add a new action: + +![](images/wsl_networking_4.png) + +The arguments should be: + + -ExecutionPolicy Bypass + +Save the action, then select it and choose `Run` from the right sidebar. + +Here are some common standard ports: + +| Plugin | Port | +|-------------------|------------| +| OLA Web interface | 9090 | +| OLA RDM tests | 9099 | +| ArtNet | 6454 | +| E1.31 (sACN) | 5568-5569 | +| Enttec ESP Net | 3333 | +| KiNet | 6038 | +| Pathport | 3792 | +| Strand ShowNet | 2501 | + +Start/Stop OLA +============== + +When you wish to use OLA, open Debian from the Start Menu and run: + + sudo service rsyslog start + sudo service dbus start + sudo service olad start + +OLA will continue to run in the background, regardless of whether the Debian command prompt is open or not. + +To stop, run: + + sudo service olad stop diff --git a/download_and_install/compiling_from_source.md b/download_and_install/compiling_from_source.md new file mode 100644 index 0000000..cfb47a0 --- /dev/null +++ b/download_and_install/compiling_from_source.md @@ -0,0 +1,281 @@ +Compiling From Source +===================== + +OLA developers recommend using the latest [pre-built packages](download_and_install). Compile from source if a release +is not available for your system, you wish to try bleeding-edge features, or want to contribute to development. + +**Before compiling and installing from source, be sure to remove any pre-packaged OLA installations, as they will likely +conflict.** + +If you're testing development releases and find an issue, please report it on +the [issue tracker](https://github.com/OpenLightingProject/ola/issues). + +OLA source code lives on [GitHub](https://github.com/OpenLightingProject/ola). Stable releases are available from +the [releases page](https://github.com/OpenLightingProject/ola/releases); this is what you want if compiling only +because OLA is not packaged on your system. For the latest code, +run `git clone https://github.com/OpenLightingProject/ola.git`. + +OLA uses `MAJOR.MINOR.PATCH` branches. The latest development happens on the `master` branch. Features and fixes under +testing are in the minor branch (i.e. `0.x`). Releases are on the patch branch (i.e. `0.10.x`). Checkout your preferred +level of stability with `git checkout ` or a final release with `git checkout tags/`. If you're a +developer, work against the `master` branch for new features, or the relevant minor branch for bug fixes. +See `README.developer` for more developer advice. + +Dependencies +============ + +OLA depends on the following third-party libraries: + +- [avahi](https://www.avahi.org) if you want to use network discovery. +- [microhttpd](https://www.gnu.org/software/libmicrohttpd/) (if you want the web UI). +- autoconf +- automake +- cppunit +- ncurses +- lex (or flex) +- libftdi +- liblo +- libtool +- libusb +- pkg-config +- [Protobuf](https://developers.google.com/protocol-buffers) (version 3.6 or later) +- uuid or ossp uuid +- yacc (or bison) +- zlib + +The Python library also requires: + +- Numpy +- Protobuf for Python + +Debian/Ubuntu +------------- + +Debian/Ubuntu users can install all dependencies with: + + sudo apt-get install \ + autoconf \ + automake \ + bison \ + flex \ + g++ \ + libavahi-client-dev \ + libcppunit-dev \ + libftdi-dev \ + liblo-dev \ + libmicrohttpd-dev \ + libncurses-dev \ + libprotobuf-dev \ + libprotoc-dev \ + libtool \ + libusb-1.0.0-dev \ + make \ + protobuf-compiler \ + pkg-config \ + uuid-dev \ + zlib1g-dev + +CentOS/RHEL/Fedora +------------------ + +Distributions using RPM packages can install all dependencies with: + + sudo dnf install \ + autoconf \ + automake \ + avahi-devel \ + bison \ + cppunit-devel \ + flex \ + gcc-c++ \ + libftdi-devel \ + liblo-devel \ + libmicrohttpd-devel \ + libtool \ + libusbx-devel \ + make \ + ncurses-devel \ + protobuf-lite-devel \ + uuid-devel \ + zlib-devel + +macOS +----- + +Dependencies are available from [MacPorts](https://www.macports.org/): + + sudo port install \ + autoconf \ + automake \ + bison \ + cppunit \ + flex \ + libftdi1 \ + liblo \ + libmicrohttpd \ + libtool \ + libusb \ + libuuid \ + ncurses \ + pkgconfig \ + protobuf3-cpp \ + zlib + +or [Homebrew](https://brew.sh/): + + brew install \ + autoconf \ + automake \ + bison \ + cppunit \ + flex \ + libftdi \ + liblo \ + libmicrohttpd \ + libtool \ + libusb \ + libuuid \ + ncurses \ + pkg-config \ + protobuf \ + zlib + +Python dependencies +------------------- + +If you wish to build the Python library, additional libraries are required: + +### From apt (preferred on Debian/Ubuntu) + + sudo apt-get install \ + python3-numpy \ + python3-protobuf + +### From dnf (preferred on CentOS/RHEL/Fedora) + + sudo dnf install \ + python3-numpy \ + python3-protobuf + +### From MacPorts + + sudo port install \ + py-numpy \ + py-protobuf3 + +### From Homebrew + + brew install \ + numpy \ + protobuf + +The `protobuf` package from Homebrew installs both the C++ and Python Protobuf components. + +### From pip + + pip3 install --user \ + numpy \ + protobuf + +Note that there are known problems with the client library on Ubuntu when using libraries from pip. + +Build +===== + +If this is the first time compiling with this download, generate the build system: + + autoreconf -i + +OLA uses autotools for building. Run `./configure --help` to see all options. + +If building OLA for a specific purpose, or on a low-power system such as a Raspberry Pi, consider +using `--disable-all-plugins` and enabling only the specific plugins you plan on using. For example: + + ./configure --disable-all-plugins --enable-e131 --enable-osc + +will build only the E1.31 (sACN) and OSC plugins, saving significant build time. + +Other popular options are `--enable-python-libs` for using the Python client library, or `--enable-rdm-tests` for the +RDM responder tests. + +Once you’ve decided on the options, it’s time to build OLA. + + ./configure + make -j$(nproc) + make check + sudo make install + +Mac users should use `make -j$(sysctl -n hw.logicalcpu)` instead of `make -j$(nproc)`. + +Finally, run `sudo ldconfig` to make new libraries available. + +Device Configuration +==================== + +Some devices (particularly those that connect via USB) require specific configuration to function. +See [here](https://www.openlighting.org/ola/getting-started/device-specific-configuration/) for instructions on +configuring common devices. + +Known Issues +============ + +If you get an error like the following: + + /bin/sh ./libtool --tag=CC --mode=compile gcc -DHAVE_CONFIG_H -I. -I/opt/local/var/macports/software/protobuf-cpp/2.0.3_0/opt/local/include/ -g -O2 -c -o ltdl.lo ltdl.c + ./libtool: line 464: CDPATH: command not found + /Users/simonn/lighting/lla/libltdl/libtool: line 464: CDPATH: command not found + /Users/simonn/lighting/lla/libltdl/libtool: line 1142: func_opt_split: command not found + libtool: Version mismatch error. This is libtool 2.2.6, but the + libtool: definition of this LT_INIT comes from an older release. + libtool: You should recreate aclocal.m4 with macros from libtool 2.2.6 + libtool: and run autoconf again. + +Your system uses a different version of libtool. Run: + + libtoolize --ltdl -c -f + +and then start from the autoreconf step again. + +If you should get the following error try to fix it with one of +[two available solutions](https://groups.google.com/group/open-lighting/msg/72060f6327d30df6): + + Rpc.pb.cc: In copy constructor 'ola::rpc::RpcMessage::RpcMessage(const ola::rpc::RpcMessage&)': + Rpc.pb.cc:143: error: base class 'class google::protobuf::Message' should be explicitly initialized in the copy constructor + +try using the `--disable-fatal-warnings` option. + +If you get + + In file included from ./common/rdm/PidStoreLoader.h:32:0, + from common/rdm/PidStore.cpp:24: + ./common/rdm/Pids.pb.h:17:2: error: #error This file was generated by an older version of protoc which is + #error This file was generated by an older version of protoc which is + ^ + ./common/rdm/Pids.pb.h:18:2: error: #error incompatible with your Protocol Buffer headers. Please + #error incompatible with your Protocol Buffer headers. Please + ^ + ./common/rdm/Pids.pb.h:19:2: error: #error regenerate this file with a newer version of protoc. + #error regenerate this file with a newer version of protoc. + +Then you should run `make clean` to clean out the old protobuf files. + +Optional +======== + +Doxygen Documentation +--------------------- + +There is also an option to build the doxygen documentation! To do so, you will need to install +[doxygen](http://www.doxygen.nl/manual/install.html) (available from package managers on all popular systems). + +Once you have installed Doxygen you may need to run `./configure` in your source directory to generate the correct +makefile. To build the docs just use: + + make doxygen-doc + +You’ll have to run a webserver to get the experience. A simple way to do this is to navigate to `html` in your source +directory and run: + + python3 -m http.server 8000 --bind 127.0.0.1 + +This starts a web server at http://127.0.0.1:8000. diff --git a/download_and_install/download_and_install.md b/download_and_install/download_and_install.md new file mode 100644 index 0000000..7283446 --- /dev/null +++ b/download_and_install/download_and_install.md @@ -0,0 +1,53 @@ +Download and Install +==================== + +Pre-built binaries +------------------ + +OLA is available pre-built on many platforms: + +### Debian/Ubuntu (including Raspberry Pi) + +Raspberry Pi users may want to see the [Raspberry Pi Quick-Start Guide](ola_on_raspberry_pi) + +Ubuntu users will need the `universe` repository enabled. +See [here](https://help.ubuntu.com/community/Repositories/Ubuntu) for details. + + sudo apt-get update + sudo apt-get install ola + +### OpenSUSE + +Available from [multimedia:libs](https://build.opensuse.org/package/show/multimedia:libs/ola): + + sudo zypper addrepo https://download.opensuse.org/repositories/multimedia:/libs/ multimedia_libs + sudo zypper install ola + +If this is the first time software is installed from multimedia:libs, you may need to accept their package signing key. + +### Gentoo + +Gentoo packages are in progress [here](https://github.com/gentoo/gentoo/pull/19420). + +### macOS + +Available from [MacPorts](https://ports.macports.org/port/ola/summary): + + sudo port install ola + +or [Homebrew](https://formulae.brew.sh/formula/ola#default): + + brew install ola + +Build from source +----------------- + +To stay on the bleeding edge with new and exciting features, [compile from source](compiling_from_source) + +Windows +------- + +OLA is not presently available directly on Windows. However, it can be used inside a virtual machine. Because of the +overhead of virtualization, there may be a small performance penalty. For show-critical uses, consider using a Linux +system, such as a [Raspberry Pi](ola_on_raspberry_pi). If you wish to test OLA on your Windows PC, see +the [VirtualBox instructions](virtualbox). diff --git a/download_and_install/images/virtualbox_1.png b/download_and_install/images/virtualbox_1.png new file mode 100644 index 0000000..6d5e68e Binary files /dev/null and b/download_and_install/images/virtualbox_1.png differ diff --git a/download_and_install/images/virtualbox_10.png b/download_and_install/images/virtualbox_10.png new file mode 100644 index 0000000..7eef4d6 Binary files /dev/null and b/download_and_install/images/virtualbox_10.png differ diff --git a/download_and_install/images/virtualbox_11.png b/download_and_install/images/virtualbox_11.png new file mode 100644 index 0000000..59b40be Binary files /dev/null and b/download_and_install/images/virtualbox_11.png differ diff --git a/download_and_install/images/virtualbox_12.png b/download_and_install/images/virtualbox_12.png new file mode 100644 index 0000000..e115bbe Binary files /dev/null and b/download_and_install/images/virtualbox_12.png differ diff --git a/download_and_install/images/virtualbox_13.png b/download_and_install/images/virtualbox_13.png new file mode 100644 index 0000000..63f1548 Binary files /dev/null and b/download_and_install/images/virtualbox_13.png differ diff --git a/download_and_install/images/virtualbox_14.png b/download_and_install/images/virtualbox_14.png new file mode 100644 index 0000000..57a6aeb Binary files /dev/null and b/download_and_install/images/virtualbox_14.png differ diff --git a/download_and_install/images/virtualbox_2.png b/download_and_install/images/virtualbox_2.png new file mode 100644 index 0000000..2ff3ae0 Binary files /dev/null and b/download_and_install/images/virtualbox_2.png differ diff --git a/download_and_install/images/virtualbox_3.png b/download_and_install/images/virtualbox_3.png new file mode 100644 index 0000000..b9ea834 Binary files /dev/null and b/download_and_install/images/virtualbox_3.png differ diff --git a/download_and_install/images/virtualbox_4.png b/download_and_install/images/virtualbox_4.png new file mode 100644 index 0000000..77a9b40 Binary files /dev/null and b/download_and_install/images/virtualbox_4.png differ diff --git a/download_and_install/images/virtualbox_5.png b/download_and_install/images/virtualbox_5.png new file mode 100644 index 0000000..4e0fd89 Binary files /dev/null and b/download_and_install/images/virtualbox_5.png differ diff --git a/download_and_install/images/virtualbox_6.png b/download_and_install/images/virtualbox_6.png new file mode 100644 index 0000000..fd89583 Binary files /dev/null and b/download_and_install/images/virtualbox_6.png differ diff --git a/download_and_install/images/virtualbox_7.png b/download_and_install/images/virtualbox_7.png new file mode 100644 index 0000000..f07a38f Binary files /dev/null and b/download_and_install/images/virtualbox_7.png differ diff --git a/download_and_install/images/virtualbox_8.png b/download_and_install/images/virtualbox_8.png new file mode 100644 index 0000000..10142cf Binary files /dev/null and b/download_and_install/images/virtualbox_8.png differ diff --git a/download_and_install/images/virtualbox_9.png b/download_and_install/images/virtualbox_9.png new file mode 100644 index 0000000..eedf6cb Binary files /dev/null and b/download_and_install/images/virtualbox_9.png differ diff --git a/download_and_install/images/wsl_networking_1.png b/download_and_install/images/wsl_networking_1.png new file mode 100644 index 0000000..baddd41 Binary files /dev/null and b/download_and_install/images/wsl_networking_1.png differ diff --git a/download_and_install/images/wsl_networking_2.png b/download_and_install/images/wsl_networking_2.png new file mode 100644 index 0000000..eebe7f6 Binary files /dev/null and b/download_and_install/images/wsl_networking_2.png differ diff --git a/download_and_install/images/wsl_networking_3.png b/download_and_install/images/wsl_networking_3.png new file mode 100644 index 0000000..9088c06 Binary files /dev/null and b/download_and_install/images/wsl_networking_3.png differ diff --git a/download_and_install/images/wsl_networking_4.png b/download_and_install/images/wsl_networking_4.png new file mode 100644 index 0000000..a61cd37 Binary files /dev/null and b/download_and_install/images/wsl_networking_4.png differ diff --git a/download_and_install/images/wsl_networking_5.png b/download_and_install/images/wsl_networking_5.png new file mode 100644 index 0000000..50c2c0a Binary files /dev/null and b/download_and_install/images/wsl_networking_5.png differ diff --git a/download_and_install/ola_on_raspberry_pi.md b/download_and_install/ola_on_raspberry_pi.md new file mode 100644 index 0000000..20c2081 --- /dev/null +++ b/download_and_install/ola_on_raspberry_pi.md @@ -0,0 +1,70 @@ +OLA on Raspberry Pi +=================== + +This tutorial describes how to get OLA running on the +[Raspberry Pi](https://www.raspberrypi.org/). The procedure described here is designed to get OLA up and running as +easily as possible. There is plenty of information on +the [Raspberry Pi Docs](https://www.raspberrypi.org/documentation/). +The [Raspberry Pi Forum](https://www.raspberrypi.org/forums/) is a good place to ask for help on Raspberry Pi specific +issues. + +Getting Started +=============== + +See the official [setup guide](https://www.raspberrypi.org/documentation/setup/) for hardware requirements. + +- A monitor is not strictly required to use OLA, but one can be helpful for debugging purposes. +- If you plan on using a USB DMX interface that does not use its own power supply, you will also need a powered USB hub. + The Raspberry Pi hardware cannot supply enough power over USB to meet the needs of most USB DMX interfaces. +- A wired network connection is strongly recommended when using OLA with any network protocols. Remember, DMX over WiFi + is not Wireless DMX! + +Installation +============= + +OLA is easily available when using [Raspberry Pi OS](https://www.raspberrypi.org/software/operating-systems/). If your +Raspberry Pi will only be used for OLA, use the "Raspberry Pi OS Lite" operating system. + +Follow the official installation instructions +[here](https://www.raspberrypi.org/documentation/installation/installing-images/) to install the OS. + +Starting Up +=========== + +If you don't have a display and keyboard, follow the SSH instructions +[here](https://www.raspberrypi.org/documentation/remote-access/ssh/README.md). This guide will assume you are typing +directly into the Raspberry Pi or have established an SSH session. + +Installing +---------- + +As with other Debian Linux systems, installing OLA can be performed by running + + sudo apt-get update + sudo apt-get install ola + +in the terminal. + +Reboot the device with `sudo reboot` to begin using OLA. + +Updating +-------- + +It’s best to always use the latest version of OLA. To update your install, run + + sudo apt-get update + sudo apt-get upgrade + +in the terminal. + +Connecting +========== + +At this point everything should be running. You can access the OLA web UI by opening a web browser and typing: + + http://:9090 + +Config and Log files +==================== + +Config files are in `/etc/ola`. OLA logs to syslog, so logs are in `/var/log/syslog`. diff --git a/download_and_install/virtualbox.md b/download_and_install/virtualbox.md new file mode 100644 index 0000000..4cd69e0 --- /dev/null +++ b/download_and_install/virtualbox.md @@ -0,0 +1,117 @@ +OLA inside VirtualBox +===================== + +These instructions explain how to install OLA inside a virtual machine. + +Downloads +========= + +Download VirtualBox from [here](https://www.virtualbox.org/wiki/Downloads). + +Also download the latest Debian release from [here](https://www.debian.org/distrib/netinst). + +Setup Virtual Machine +===================== + +Open VirtualBox and choose Machine > New. On the first screen, enter a name for your virtual machine and choose Debian +Linux. The remainder of the defaults are fine. + +![](images/virtualbox_1.png) + +Once your machine is created, select it in the sidebar and choose Settings. Select Network from the sidebar and set it +to "Bridged Adapter". + +![](images/virtualbox_2.png) + +Now click Start. A "Select start-up disk" window will appear, as the machine is not initialized. Click the folder icon, +then Add, then browse to your download Debian ISO file. The Debian installer will begin. + +![](images/virtualbox_3.png) + +Press enter on "Graphical install" + +![](images/virtualbox_4.png) + +The installer will ask you about your language, location, and keyboard. + +When asked for a hostname, choose something sensible. Leave the domain name empty unless you already know you need to +put something there. + +![](images/virtualbox_5.png) + +Set a root and user password you will remember. You'll need them later. + +Configure the clock to your local time zone. + +Continue to select the default options. When asked "Write the changes to disks?" select "Yes" and Continue. + +![](images/virtualbox_6.png) + +Debian will take a bit to install. Eventually you'll be asked to scan additional CD/DVDs. There are none, so accept the +defaults, entering a proxy if your network requires one. + +When the Software selection menu appears, select only "SSH server" and "standard system utilities". + +![](images/virtualbox_7.png) + +The software will install. Choose to install the GRUB boot loader to the master boot record. Select the only disk +available. + +![](images/virtualbox_8.png) + +![](images/virtualbox_9.png) + +When installation is complete, choose continue. The system will reboot. When the screen looks like below, it's ready: + +![](images/virtualbox_10.png) + +Installation +============ + +Type your username from earlier in the setup process, followed by Enter. Then type your password (it won't be visible as +you type), followed by Enter. + +![](images/virtualbox_11.png) + +Enter the following commands + + su + apt-get update + apt-get install ola + +Type `Y` to continue. Then run `/sbin/reboot` to reboot the machine. + +Log in again once the machine is rebooted. Find the system's IP address with `ip addr`. An example of the output with +the address highlighted is below: + +![](images/virtualbox_12.png) + +Visit `https://:9090` in a browser for OLA's web interface. + +Shutdown +======== + +To shutdown the system, use the VirtualBox window: Machine > ACPI Shutdown. + +Troubleshooting +=============== + +No plugins +---------- + +If your system is too fast, OLA may start before the network is available. You'll know this has happened when the +"Primary IP" is `0.0.0.0` and very few plugins are available: + +![](images/virtualbox_13.png) + +![](images/virtualbox_14.png) + +There is a simple fix - just click "Reload Plugins" on the main page. Now, adding/editing universes will show all +available plugins, although the displayed network information wil be out of date. + +If you need to know the new network information, log in and run: + + su + systemctl restart olad + +Refresh the web interface. A real IP address should be listed and plugins should be available.