Getting Started

arkOS and Genesis are still in development. Many tools are not yet working, and you should not yet depend on arkOS for anything other than testing at this time. Please stay connected via one of the methods listed on the Contact page to get updates on project development.

This version of the Getting Started guide will show you how to install arkOS from your home computer, set it up on your desired hardware, and begin using the Genesis management suite.

First Steps: Installing arkOS

Download the version of the arkOS Assistant that corresponds to your operating system from the download page. Once downloaded, insert a blank SD card with at least 8GB of space into your computer (and a USB drive if you want to use a split boot/data configuration, explained below), and run the Assistant, which should have added itself into your Applications menu. If you installed the Assistant via the source package on Linux, you can run it by entering the directory you extracted the package to on the command line, then running ./arkOS Assistant.

The Assistant will come up and, after having chosen to install arkOS, it will walk you through the steps of installing arkOS to the SD card. First, it will ask you to choose your hardware type. Next, it will ask you to choose an installation method. A Default configuration will install the entire operating system to one SD card, suitable for running your entire server. A Split Boot/Data configuration installs the boot data to the SD card, but installs the rest of the system to a USB drive. The split boot/data configuration is generally more dependable than just using an SD card, as SD cards can wear down over time and experience corrupted data.

Once you've chosen your hardware and install method, you can choose the download server that is closest to you. Finally, you will be asked to choose which device corresponds to your SD card. Click the line of the disk that corresponds to your SD card writer. If you chose a split boot/data configuration, click the USB device you wish to use for the data partition after the SD card. You can see which device will be used for what on the right-hand side of the table.

It is very important that you choose the correct disk at this stage, if not it may lead to data loss. To help you choose the right one: memory cards on Linux often start with the name /dev/mmcblk. Also, the label and size of each disk device is listed next to it in the table.

After you’ve chosen a download server and disk device(s), the Assistant will automatically download the image from our servers, then write it to the device(s) you select. This will take a few minutes, depending on the speed of your computer and your internet connection. Once the process is complete, the Assistant will let you know and you can disconnect the SD card.

Starting arkOS

Connect the SD card (and USB drive if you chose a split boot/data configuration) to your hardware, and plug it into an ethernet port on your home router. Start up the device by plugging in a power cable. Give it a minute to start up, then hop back onto your computer and click Search Network in the Assistant. If everything has been configured correctly, your device will show up in the list and you can click its name to launch the Genesis management interface. If you do not want to use arkOS Assistant to find your server on your network, you can try connecting to the following web address in your browser: http://arkOS.local:8000

If, for some reason, you cannot reach your arkOS server via the Assistant or the above address, there may be an issue with how DNS is configured on your local network. In your browser window, you can replace arkOS.local by the IP address of the device, which you can get by using your home router's administration interface.

After successfully connecting, the First Run wizard will appear. It will ask you to set up an initial user that you can use with arkOS to manage your services. Next, you will see a list of options for setting up your new arkOS server, like the name, timezone, etc. You will then be taken to a screen to choose the applications you’d like to install. Choose the applications based on what you would like to be able to run on your arkOS server, and what you want to be able to manage. Click Select to choose them. They will be automatically downloaded from the central repository, and the required server packages that run in the background will also be installed. This process should take a minute or two depending on your connection speed and how many applications you choose.

Once you've finished selecting the applications you want, click Setup. You will be taken to a page where you can monitor the progress of the installation. Once a minimum number of tasks has been completed successfully, an OK button will appear, allowing you to log in with your newly-created user and start using arkOS. If you chose several applications to install, these might continue to install in the background while you start to use arkOS.

If you have questions or encounter errors, visit the Community page and you can receive help there. Keep in mind that arkOS is still under development, so many of its features may still be works-in-progress.

Installing arkOS to a PC or unsupported device

If you are able to run Arch Linux on a PC or a type of embedded device that we don't currently have images for, chances are you are also able to run arkOS on it! Once you have Arch installed, run:

curl -s https://pkg.arkos.io/resources/install_arch.py | sudo python

The installation process will begin to convert your system to arkOS. Please note that this script performs a full system conversion to arkOS, meaning that it may change many system settings to match what an initial arkOS install is supposed to look like. Make sure this is really what you want (and that you are willing to essentially sacrifice the current Arch install) before you proceed.

Manually writing a disk image

If you are not able to use the arkOS Assistant to install your disk image, you have several options for writing it depending on your operating system:

Windows

Download Win32DiskImager and install it. Download the appropriate image from the Downloads page depending on your target platform. Extract the .zip file to a location of your choice. Insert the SD card (and/or USB drive). Open Win32DiskImager and write the .img file to the appropriate device shown in Win32DiskImager.

macOS

Download the appropriate image from the Downloads page depending on your target platform. Extract the .tar.gz or .zip file to a location of your choice. Insert the SD card (and/or USB drive). Open Disk Utility, and partition your SD card : Partition Layout = “1 partition” ; Format : “Free Space”. Open the terminal and check your device(s) with diskutil list. Once you are certain you see the correct disk in the list, write the image with sudo dd bs=1m if=/path/to/image/file.img of=/dev/rdiskX, replacing the path to the image file, and the disk identifier, in the appropriate places. Note that the disk identifier has an extra r in it – that is normal and will make your writing process go much faster on macOS (less than 10 minutes). If the write operation fails because of the “bs=1m” parameter, remove it. Please note that the write operation may take some time! Also note that you must write to the whole disk (like /dev/rdisk0) and NOT to an individual partition.

For a split boot/data configuration, write the .img file marked boot to the SD card and data file to the USB drive. You may use the same steps above for each device.

Linux

Download the appropriate image from the Downloads page depending on your target platform. Extract the .tar.gz or .zip file to a location of your choice. Insert the SD card (and/or USB drive). Open the terminal and check your device(s) with lsblk. Once you are certain you see the correct disk in the list, write the image with sudo dd bs=1M if=/path/to/image/file.img of=/dev/sdx, replacing the path to the image file, and the disk identifier, in the appropriate places. Note that you must write to the whole disk (like /dev/sdx) and NOT to an individual partition.

For a split boot/data configuration, write the .img file marked boot to the SD card and data file to the USB drive. You may use the same steps above for each device.