Alpine Linux - User contributions [en]

Installing Alpine Linux on OrangePi RV2

2026-04-15T21:33:59Z

Aarch0x40:

{{Draft}}
[[Main Page]] > [[:Category:Architectures|Architectures]] > [[Riscv64]] > Installing Alpine Linux on OrangePi RV2
 
{{Warning|The contributors to the Alpine Linux project are not responsible for any damage/loss experienced by using the following guide. This article is provided as a general reference. It is assumed that the implementer will have the knowledge and ability to close the gap between what is described here and their specific setup.
 Implementers of this guide should consider the result development / alpha quality.}}

The [http://www.orangepi.org/html/hardWare/computerAndMicrocontrollers/details/Orange-Pi-RV2.html OrangePi RV2] is a credit-card sized development board with a Ky X1 8-Core SoC. The Ky X1 is for all intents and purposes a SpacemiT K1 SoC. The remainder of this guide is more likely to use the terms SpacemiT or K1 as is prevalent throughout the Linux community. Please understand that these terms all refer to the same RISC-V ISA implementation.

This guide assumes that the manufacturer provided [https://github.com/riscv-software-src/opensbi OpenSBI] and [https://u-boot.org/ U-Boot] binaries have been applied to the SPI Flash device. This stock bootloader will look for an <code>extlinux/extlinux.conf</code> which will be used to configure the boot process.

Those following this guide may find it useful to have a USB UART serial cable available to debug kernel loading.

This guide borrows heavily from the article [https://arvanta.net/alpine/install-alpine-riscv64-qemu-uboot/ install Alpine Linux riscv64 under qemu with u-boot loader] by Milan P. Stanić and posted to [[Riscv64]] by [[User:AnIDFB]].

== Known issues ==
 
{{Warning|The following are the issues that are known to exist between the result of this guide and the manufacturer provided image}}

* Wireless (Wi-Fi & Bluetooth) is not functional
* Some kernel sources have an issue with starting the framebuffer
* Manufacturer tools are not included

This guide was assembled as a dumping of my personal notes. It's being updated as I come across new information. Alpine does run on the RV2 albeit not directly out of the box. Will do my best to reference external materials so that this article may provide some insight to others while still under development. The above may not be the only issues but hopefully there's enough information here to get you going.

== Kernel and Firmware ==
There are a few different options for kernels. The extent of coverage documented here is largely due to my initial ignorance. I have found a few sources for mostly workable kernels. None of them works 100%. SpacemiT is still in the process upstreaming functionality.

=== Obtaining the ESOS firmware ===
The processor being used on the RV2 requires a firmware to function properly. This file is available from the vendor images, in third party distributions and in the [https://github.com/orangepi-xunlong/orangepi-build orangepi-xunlong/orangepi-build] GitHub repository. The subdirectory containing the required file is [https://github.com/orangepi-xunlong/orangepi-build/tree/next/external/packages/bsp/ky/usr/lib/firmware external/packages/bsp/ky/usr/lib/firmware]. Download the file <code>esos.elf</code>. Keep the download in a safe place and also <code>/lib/firmware</code>. The <code>/lib/firmware</code> directory is also where you'll find this file within the vendor's image or an initrd image.
{{Note|
Changes to mkinitfs will be needed in order for this firmware to be included. More information on that will be provided further down the document}}

=== Why not the Alpine Kernel? ===
The kernels available from the Alpine Linux Project won't completely boot. U-Boot is able to load and run the kernel. The kernel is able to unpack the initramfs image and start the init process. The kernel panics though because the init process fails to mount a root filesystem. The init process is unable to mount a root filesystem because the kernel doesn't have the capability to load the esos.elf firmware. This capability is provided by the remoteproc driver. My experience with the RV2 so far shown that loading this firmware is required for enabling the full function of the K1/X1 SoC.

=== Obtaining the Vendor kernel ===
Open a browser to the [http://www.orangepi.org/html/hardWare/computerAndMicrocontrollers/service-and-support/Orange-Pi-RV2.html OrangePI RV2 Download] page.

Click on the "Downloads" button for the Ubuntu Image. This will take you to a Google Drive folder. Download the Orangepirv2_1.0.0_ubuntu_noble_server_linux6.6.63.7z.

Decompress this file after downloading using your favorite archive utility. It will expand to a directory containing Orangepirv2_1.0.0_ubuntu_noble_server_linux6.6.63.img and shasum file.

Attach the image to a loop device and mount the root partition.
<pre># Find the first available loop device
doas losetup --find

# Assuming the first found available device is /dev/loop0
doas losetup -P /dev/loop0 Orangepirv2_1.0.0_ubuntu_noble_server_linux6.6.63.img

# Mount the root slice
doas mount /dev/loop0p1 /mnt
</pre>

Archive the vendor kernel
<pre>cd /mnt
tar czf /var/tmp/linux-6.6.63-ky.tgz boot/vmlinuz-6.6.63-ky boot/System.map-6.6.63-ky boot/config-6.6.63-ky boot/dtb-6.6.63-ky lib/modules/6.6.63-ky</pre>
{{Note|
You probably want to put the resulting archive in a safer place than /var/tmp at this point. There's a bit to do before we'll need it.}}

Unmount and detach the vendor image
<pre>cd -
doas umount /mnt
doas losetup -d /dev/loop0</pre>
=== Building from source ===
There have been 2 main repositories for patched kernel sources.

* [https://github.com/jasonmontleon/linux-spacemit jasonmontleon/linux-spacemit]
* [https://github.com/BredOS/linux-bredos BredOS/linux-bredos]

The linux-spacemit repository is used by RedHat employee Jason Montleon in building out their RISCV64 support. The linux-bredos repository is used by the BredOS project which supports the RV2 and has provides downloadable images for the board. There is cross contribution between these two repositories. A lot of what I've learned to assemble this guide is attributed to these projects.

==== Setting up a workspace ====

Begin by setting up a RISC-V workspace by following [[Riscv64|Running Alpine riscv64 in QEMU]]. You'll need to establish a build environment in this QEMU guest.

<pre>doas apk add alpine-sdk bison flex openssl-dev ncurses ncurses-dev</pre>

{{Note|
<code>ncurses</code> and <code>ncurses-dev</code> aren't a hard requirements but are useful if you want to run <code>make menuconfig</code>}}

==== Cloning the source, configuring and building the kernel ====

{{Note|
This is needs a redo.}}

== Preparing the media ==

=== Partition and setup the filesystems ===
==== Install parted package ====
<pre>doas apk add parted</pre>
==== Insert, partition and format the boot media ====

The media can be either an SD card or USB drive. An 2280 PCIe NVMe is also possibly if you have the ability to write it from the host setting up the media. For the purposes of this guide we will refer to our boot media as <code>/dev/sdb</code>. The following section requires a root shell.

<pre>alias p="parted -sa optimal /dev/sdb"
p mklabel gpt
p mkpart boot ext4 0G 512M
p set 1 boot
p mkpart root ext4 512M 100%
p p</pre>

The final command should produce output to confirm the result of the executed commands. It should look something like the following.

<pre>Model: Generic STORAGE DEVICE (scsi)
Disk /dev/sdb: 15.5GB
Sector size (logical/physical): 512B/512B
Partition Table: gpt
Disk Flags:

Number Start End Size File system Name Flags
1 1049kB 512MB 511MB ext4 boot boot, esp
2 512MB 15.5GB 15.0GB root
</pre>

If all looks good, then we can proceed with formatting the partitions

<pre>mkfs.ext4 /dev/sdb1 && mkfs.ext4 /dev/sdb2</pre>

Mount the filesystems and lay some preliminary groundwork.

<pre># Mount the target root slice
mount /dev/sdb2 /mnt

# Create mount point for boot slice
[ ! -d /mnt/boot ] && mkdir -vp /mnt/boot

# Mount boot slice
mount /dev/sdb1 /mnt/boot

# Create directory for extlinux config
[ ! -d /mnt/boot/extlinux ] && mkdir -vp /mnt/boot/extlinux

# Create directory for apk config
[ ! -d /mnt/etc/apk ] && mkdir -vp /mnt/etc/apk

# Create mount point for devfs
[ ! -d /mnt/dev ] && mkdir -vp /mnt/dev

# Create mount point for procfs
[ ! -d /mnt/proc ] && mkdir -vp /mnt/proc

# Create mount point for sysfs
[ ! -d /mnt/sys ] && mkdir -vp /mnt/sys

# Use bind mounts for dev proc and sys within the target device
mount -o bind /dev /mnt/dev && mount -o bind /proc /mnt/proc && mount -o bind /sys /mnt/sys

# Configure apk package manager
cat <<EOF > /mnt/etc/apk/repositories
#/media/vda1/apks
http://dl-cdn.alpinelinux.org/alpine/edge/main
http://dl-cdn.alpinelinux.org/alpine/edge/community
http://dl-cdn.alpinelinux.org/alpine/edge/testing
EOF
</pre>
== Install Alpine from an Alpine host ==

=== Install Alpine with apk ===
Some of what is going to be installed is up to your choosing. This should be enough to get you going and demonstrate how to target an apk installation.
<pre>apk --root /mnt --arch riscv64 --allow-untrusted --initdb add \
alpine-base alpine-baselayout alpine-conf alpine-keys alpine-release alpine-baselayout-data \
kmod openrc dbus util-linux blkid chrony sysfsutils ssl_client openssh ca-certificates-bundle \
alpine-keys ethtool e2fsprogs e2fsprogs-extra libudev-zero libudev-zero-helper parted grep \
busybox-mdev-openrc procps-ng net-tools coreutils doas sed gawk findutils bash shadow pciutils \
mkinitfs</pre>

=== Setup openrc services ===
<pre>for rc in boot/bootmisc boot/hostname boot/modules boot/sysctl boot/urandom boot/networking \
sysinit/devfs sysinit/hwdrivers sysinit/mdev sysinit/modules \
shutdown/mount-ro shutdown/killprocs \
default/dbus default/networking default/chronyd default/local; do
ln -s /etc/init.d/"${rc##*/}" /mnt/etc/runlevels/"$rc"
done</pre>

=== Setup fstab ===
<pre>cp /mnt/etc/fstab /mnt/etc/fstab.orig
echo $(blkid /dev/sdb2 | sed 's/.*: //;s/ .*//;s/"//g') / \ \ \ \ ext4 rw,relatime 0 1 > /mnt/etc/fstab.new
echo $(blkid /dev/sdb1 | sed 's/.*: //;s/ .*//;s/"//g') /boot ext4 rw,relatime 0 2 >> /mnt/etc/fstab.new
cat /mnt/etc/fstab.orig >> /mnt/etc/fstab.new
cp /mnt/etc/fstab.new /mnt/etc/fstab</pre>

=== Setup networking ===
<pre>[ ! -d /mnt/etc/network ] mkdir -vp /mnt/etc/networking
cat <<EOF > /mnt/etc/network/interfaces
auto lo
iface lo inet loopback

auto eth0
iface eth0 inet dhcp

EOF</pre>

=== Set the root password ===
When the system boots it will require a root password. This differs from Alpine install media but that's not the objective of this guide. This guide is installing a ready system.

<pre>passwd -R /mnt root</pre>

=== Enable login on UART ===
<pre>sed -i 's/^#ttyS0/ttyS0/' /mnt/etc/inittab</pre>

== Install Alpine from an non-Alpine RISC-V Linux host ==
This section is mainly intended for those trying to install Alpine from one of the vendor images or another RISCV64 install. The apk utility does need to be able to run post-build scripts in order for target installation to function properly.

=== Download a minirootfs to run apk within a chroot ===
<pre>cd /var/tmp
wget https://dl-cdn.alpinelinux.org/edge/releases/riscv64/alpine-minirootfs-20260127-riscv64.tar.gz</pre>
Unzip in /mnt
<pre>cd /mnt
tar xfpz /var/tmp/alpine-minirootfs-20260127-riscv64.tar.gz</pre>
{{Note|
If installing from a non-Alpine host, you may want to install the kernel image and modules first. Come back to this part to chroot and run the apk step and finish up with mkinitfs}}
Chroot into /mnt and run <code>apk add</code>
<pre>chroot /mnt /bin/sh
apk --arch riscv64 --allow-untrusted --initdb add \
alpine-base alpine-baselayout alpine-conf alpine-keys alpine-release alpine-baselayout-data \
kmod openrc dbus util-linux blkid chrony sysfsutils ssl_client openssh ca-certificates-bundle \
alpine-keys ethtool e2fsprogs e2fsprogs-extra libudev-zero libudev-zero-helper parted grep \
busybox-mdev-openrc procps-ng net-tools coreutils doas sed gawk findutils bash shadow pciutils \
mkinitfs</pre>

=== Setup openrc services ===
<pre>for rc in boot/bootmisc boot/hostname boot/modules boot/sysctl boot/urandom boot/networking \
sysinit/devfs sysinit/hwdrivers sysinit/mdev sysinit/modules \
shutdown/mount-ro shutdown/killprocs \
default/dbus default/networking default/chronyd default/local; do
ln -s /etc/init.d/"${rc##*/}" /etc/runlevels/"$rc"
done</pre>

=== Setup fstab within the chroot ===
<pre>cp /etc/fstab /etc/fstab.orig
echo $(blkid /dev/sdb2 | sed 's/.*: //;s/ .*//;s/"//g') / \ \ \ \ ext4 rw,relatime 0 1 > /etc/fstab.new
echo $(blkid /dev/sdb1 | sed 's/.*: //;s/ .*//;s/"//g') /boot ext4 rw,relatime 0 2 >> /etc/fstab.new
cat /etc/fstab.orig >> /etc/fstab.new
cp /etc/fstab.new /etc/fstab</pre>

=== Setup networking ===
<pre>[ ! -d /etc/network ] mkdir -vp /etc/networking
cat <<EOF > /etc/network/interfaces
auto lo
iface lo inet loopback

auto eth0
iface eth0 inet dhcp

EOF</pre>

=== Set the root password ===
When the system boots it will require a root password. This differs from Alpine install media but that's not the objective of this guide. This guide is installing a ready system.

<pre>passwd</pre>

=== Enable login on UART ===
<pre>sed -i 's/^#ttyS0/ttyS0/' /etc/inittab</pre>

== Setting up the boot environment ==
All of the effort up to this point has come down to this. This portion of the guide will assume the kernel being installed is version 6.6.63-ky from the vendor.
=== Install the kernel ===
We created an archive for each method of obtaining a kernel. Now we need to unpack that archive in our buildroot.
<pre>cd /mnt
tar xzf /var/tmp/linux-6.6.63-ky.tgz</pre>
=== Install the esos.elf firmware ===
Copy esos.elf from your very safe place to /mnt/lib/firmware
<pre>doas cp ~/Downloads/esos.elf /mnt/lib/firmware/</pre>
=== Creating the initrd image ===
The methods to obtain a kernel omitted collecting initrd images. Those images would not have been based on Alpine. We'll be using <code>mkinitfs</code> to do this. There are a few modifications we need to make in order for this process to generate an image with all the required bits.
==== Configuring and fixing mkinitfs ====
===== Add esos.elf to mkinitfs/features.d/base.files =====
<pre>echo "/lib/firmware/esos.elf" >> /etc/mkinitfs/features.d/base.files</pre>
===== Add the wireless-regdb database files to base.files =====
{{Note|
You may not need this. If you see a kernel message regarding failure to load regulatory.db with error -2, this will resolve it. Requires install of wireless-regdb apk package.}}
<pre>echo "/lib/firmware/regulatory.*" >> /etc/mkinitfs/features.d/base.files</pre>

===== Prevent mkinitfs from deleting needed firmware =====
The mkinitfs script will delete a directory that shouldn't exist. The files assembled from the features.d includes will have already been staged prior to mkinitfs assembling firmware needed by included modules. We need this not to happen and below is the simplest workaround I could pull together.
Make a copy of mkinitfs
<pre>cp /sbin/mkinitfs /sbin/mkinitfs-rv2</pre>
In the initfs_firmware function of <code>/sbin/mkinitfs-rv2</code> you will find the following lines
<pre> rm -rf "$tmpdir"/lib/firmware
mkdir -p "$tmpdir"/lib/firmware</pre>
Change them to be
<pre> #rm -rf "$tmpdir"/lib/firmware
[ ! -d "$tmpdir"/lib/firmware ] && mkdir -p "$tmpdir"/lib/firmware</pre>

==== Using mkinitfs-rv2 to create an initrd image ====
Installing from an Alpine host
<pre>mkinitfs-rv2 -b /mnt -c /mnt/etc/mkinitfs/mkinitfs.conf -o /mnt/boot/initramfs-6.6.63-ky 6.6.63-ky</pre>

Installing within a chroot
<pre>mkinitfs-rv2 -c /etc/mkinitfs/mkinitfs.conf -o /boot/initramfs-6.6.63-ky 6.6.63-ky</pre>
=== Configure extlinux ===
Create an extlinux.conf file with the following
<pre>default l0
menu title Alpine U-Boot menu
prompt 1
timeout 10

label l0
menu label Alpine Linux 3.24.0_alpha20260127 (Kernel 6.6.63-ky)
linux /vmlinuz-6.6.63-ky
initrd /initramfs-6.6.63-ky
fdt /dtb-6.6.63-ky/ky/x1_orangepi-rv2.dtb
append mtdparts=d420c000.spi-0:64K@0(bootinfo),64K@64K(private),256K@128K(fsbl),64K@384K(env),192K@448K(opensbi),-@640K(uboot) root=UUID=236a5824-0390-42dc-83e3-f02123188f96 console=ttyS0,115200 console=tty1 rootwait rw rootfstype=ext4 earlycon=sbi</pre>

==== A few notes on extlinux.conf ====
* Most device trees are generated in a dtbs/[kernel-version] directory.
* The vendor vmlinuz is a decompressed kernel image, though it shouldn't matter
* The mtdparts kernel parameter isn't absolutely required
* Only the right-most console statement seems to get attention. If you're on UART then you'll want <code>console=ttyS0,115200</code> and if you're on the framebuffer you'll want <code>console=tty1</code>.

== Wrapping Up ==

At this point the primary setup is complete. You may want to add some additional packages or configuration but can also be done after booting the RV2 board.

I may have forgotton something(s) which you'll soon discoven. I'll do my best to fold in corrections as I find they're needed or as new information becomes available.

=== Unmount the buildroot ===

<pre>umount /mnt/proc /mnt/sys /mnt/dev /mnt/boot /mnt</pre>

== Usability extras ==

The above should get your OrangePi RV2 booting Alpine Linux. Below are some additional configurations to help make growing your install a little easier. The following assumes you're still chroot /mnt or have booted the system.

=== Add a local user for yourself with escalation privileges ===

Create a user account for yourself with a secondary group of wheel
<pre># Create your account
useradd -G wheel -s /bin/bash -d /home/myuser -m -c "My User" myuser
# Set your password
passwd myuser</pre>

Add a configuration to doas.d for group wheel
<pre>echo permit persist :wheel > /etc/doas.d/00-wheel.conf</pre>

=== Install Avahi for mdns broadcasts ===

Avahi can broadcast names for services provided by your host. The default config in the Alpine package provides a configuration for sshd.

<pre># First setup the hostname
setup-hostname myhost

# Set the hostname
hostname `cat /etc/hostname`

# Install the avahi apk
apk add avahi

# Enable and start the avahi daemon
rc-update add avahi-daemon && rc-service avahi-daemon start</pre>

[[Category:Riscv64]]

Installing Alpine Linux on OrangePi RV2

2026-04-15T21:31:41Z

Aarch0x40:

{{Draft}}
[[Main Page]] > [[:Category:Architectures|Architectures]] > [[Riscv64]] > Installing Alpine Linux on OrangePi RV2
 
{{Warning|The contributors to the Alpine Linux project are not responsible for any damage/loss experienced by using the following guide. This article is provided as a general reference. It is assumed that the implementer will have the knowledge and ability to close the gap between what is described here and their specific setup.

Implementers of this guide should consider the result development / alpha quality.}}

The [http://www.orangepi.org/html/hardWare/computerAndMicrocontrollers/details/Orange-Pi-RV2.html OrangePi RV2] is a credit-card sized development board with a Ky X1 8-Core SoC. The Ky X1 is for all intents and purposes a SpacemiT K1 SoC. The remainder of this guide is more likely to use the terms SpacemiT or K1 as is prevalent throughout the Linux community. Please understand that these terms all refer to the same RISC-V ISA implementation.

This guide assumes that the manufacturer provided [https://github.com/riscv-software-src/opensbi OpenSBI] and [https://u-boot.org/ U-Boot] binaries have been applied to the SPI Flash device. This stock bootloader will look for an <code>extlinux/extlinux.conf</code> which will be used to configure the boot process.

Those following this guide may find it useful to have a USB UART serial cable available to debug kernel loading.

This guide borrows heavily from the article [https://arvanta.net/alpine/install-alpine-riscv64-qemu-uboot/ install Alpine Linux riscv64 under qemu with u-boot loader] by Milan P. Stanić and posted to [[Riscv64]] by [[User:AnIDFB]].

== Known issues ==
 
{{Warning|The following are the issues that are known to exist between the result of this guide and the manufacturer provided image}}

* Wireless (Wi-Fi & Bluetooth) is not functional
* Some kernel sources have an issue with starting the framebuffer
* Manufacturer tools are not included

This guide was assembled as a dumping of my personal notes. It's being updated as I come across new information. Alpine does run on the RV2 albeit not directly out of the box. Will do my best to reference external materials so that this article may provide some insight to others while still under development. The above may not be the only issues but hopefully there's enough information here to get you going.

== Kernel and Firmware ==
There are a few different options for kernels. The extent of coverage documented here is largely due to my initial ignorance. I have found a few sources for mostly workable kernels. None of them works 100%. SpacemiT is still in the process upstreaming functionality.

=== Obtaining the ESOS firmware ===
The processor being used on the RV2 requires a firmware to function properly. This file is available from the vendor images, in third party distributions and in the [https://github.com/orangepi-xunlong/orangepi-build orangepi-xunlong/orangepi-build] GitHub repository. The subdirectory containing the required file is [https://github.com/orangepi-xunlong/orangepi-build/tree/next/external/packages/bsp/ky/usr/lib/firmware external/packages/bsp/ky/usr/lib/firmware]. Download the file <code>esos.elf</code>. Keep the download in a safe place and also <code>/lib/firmware</code>. The <code>/lib/firmware</code> directory is also where you'll find this file within the vendor's image or an initrd image.
{{Note|
Changes to mkinitfs will be needed in order for this firmware to be included. More information on that will be provided further down the document}}

=== Why not the Alpine Kernel? ===
The kernels available from the Alpine Linux Project won't completely boot. U-Boot is able to load and run the kernel. The kernel is able to unpack the initramfs image and start the init process. The kernel panics though because the init process fails to mount a root filesystem. The init process is unable to mount a root filesystem because the kernel doesn't have the capability to load the esos.elf firmware. This capability is provided by the remoteproc driver. My experience with the RV2 so far shown that loading this firmware is required for enabling the full function of the K1/X1 SoC.

=== Obtaining the Vendor kernel ===
Open a browser to the [http://www.orangepi.org/html/hardWare/computerAndMicrocontrollers/service-and-support/Orange-Pi-RV2.html OrangePI RV2 Download] page.

Click on the "Downloads" button for the Ubuntu Image. This will take you to a Google Drive folder. Download the Orangepirv2_1.0.0_ubuntu_noble_server_linux6.6.63.7z.

Decompress this file after downloading using your favorite archive utility. It will expand to a directory containing Orangepirv2_1.0.0_ubuntu_noble_server_linux6.6.63.img and shasum file.

Attach the image to a loop device and mount the root partition.
<pre># Find the first available loop device
doas losetup --find

# Assuming the first found available device is /dev/loop0
doas losetup -P /dev/loop0 Orangepirv2_1.0.0_ubuntu_noble_server_linux6.6.63.img

# Mount the root slice
doas mount /dev/loop0p1 /mnt
</pre>

Archive the vendor kernel
<pre>cd /mnt
tar czf /var/tmp/linux-6.6.63-ky.tgz boot/vmlinuz-6.6.63-ky boot/System.map-6.6.63-ky boot/config-6.6.63-ky boot/dtb-6.6.63-ky lib/modules/6.6.63-ky</pre>
{{Note|
You probably want to put the resulting archive in a safer place than /var/tmp at this point. There's a bit to do before we'll need it.}}

Unmount and detach the vendor image
<pre>cd -
doas umount /mnt
doas losetup -d /dev/loop0</pre>
=== Building from source ===
There have been 2 main repositories for patched kernel sources.

* [https://github.com/jasonmontleon/linux-spacemit jasonmontleon/linux-spacemit]
* [https://github.com/BredOS/linux-bredos BredOS/linux-bredos]

The linux-spacemit repository is used by RedHat employee Jason Montleon in building out their RISCV64 support. The linux-bredos repository is used by the BredOS project which supports the RV2 and has provides downloadable images for the board. There is cross contribution between these two repositories. A lot of what I've learned to assemble this guide is attributed to these projects.

==== Setting up a workspace ====

Begin by setting up a RISC-V workspace by following [[Riscv64|Running Alpine riscv64 in QEMU]]. You'll need to establish a build environment in this QEMU guest.

<pre>doas apk add alpine-sdk bison flex openssl-dev ncurses ncurses-dev</pre>

{{Note|
<code>ncurses</code> and <code>ncurses-dev</code> aren't a hard requirements but are useful if you want to run <code>make menuconfig</code>}}

==== Cloning the source, configuring and building the kernel ====

{{Note|
This is needs a redo.}}

== Preparing the media ==

=== Partition and setup the filesystems ===
==== Install parted package ====
<pre>doas apk add parted</pre>
==== Insert, partition and format the boot media ====

The media can be either an SD card or USB drive. An 2280 PCIe NVMe is also possibly if you have the ability to write it from the host setting up the media. For the purposes of this guide we will refer to our boot media as <code>/dev/sdb</code>. The following section requires a root shell.

<pre>alias p="parted -sa optimal /dev/sdb"
p mklabel gpt
p mkpart boot ext4 0G 512M
p set 1 boot
p mkpart root ext4 512M 100%
p p</pre>

The final command should produce output to confirm the result of the executed commands. It should look something like the following.

<pre>Model: Generic STORAGE DEVICE (scsi)
Disk /dev/sdb: 15.5GB
Sector size (logical/physical): 512B/512B
Partition Table: gpt
Disk Flags:

Number Start End Size File system Name Flags
1 1049kB 512MB 511MB ext4 boot boot, esp
2 512MB 15.5GB 15.0GB root
</pre>

If all looks good, then we can proceed with formatting the partitions

<pre>mkfs.ext4 /dev/sdb1 && mkfs.ext4 /dev/sdb2</pre>

Mount the filesystems and lay some preliminary groundwork.

<pre># Mount the target root slice
mount /dev/sdb2 /mnt

# Create mount point for boot slice
[ ! -d /mnt/boot ] && mkdir -vp /mnt/boot

# Mount boot slice
mount /dev/sdb1 /mnt/boot

# Create directory for extlinux config
[ ! -d /mnt/boot/extlinux ] && mkdir -vp /mnt/boot/extlinux

# Create directory for apk config
[ ! -d /mnt/etc/apk ] && mkdir -vp /mnt/etc/apk

# Create mount point for devfs
[ ! -d /mnt/dev ] && mkdir -vp /mnt/dev

# Create mount point for procfs
[ ! -d /mnt/proc ] && mkdir -vp /mnt/proc

# Create mount point for sysfs
[ ! -d /mnt/sys ] && mkdir -vp /mnt/sys

# Use bind mounts for dev proc and sys within the target device
mount -o bind /dev /mnt/dev && mount -o bind /proc /mnt/proc && mount -o bind /sys /mnt/sys

# Configure apk package manager
cat <<EOF > /mnt/etc/apk/repositories
#/media/vda1/apks
http://dl-cdn.alpinelinux.org/alpine/edge/main
http://dl-cdn.alpinelinux.org/alpine/edge/community
http://dl-cdn.alpinelinux.org/alpine/edge/testing
EOF
</pre>
== Install Alpine from an Alpine host ==

=== Install Alpine with apk ===
Some of what is going to be installed is up to your choosing. This should be enough to get you going and demonstrate how to target an apk installation.
<pre>apk --root /mnt --arch riscv64 --allow-untrusted --initdb add \
alpine-base alpine-baselayout alpine-conf alpine-keys alpine-release alpine-baselayout-data \
kmod openrc dbus util-linux blkid chrony sysfsutils ssl_client openssh ca-certificates-bundle \
alpine-keys ethtool e2fsprogs e2fsprogs-extra libudev-zero libudev-zero-helper parted grep \
busybox-mdev-openrc procps-ng net-tools coreutils doas sed gawk findutils bash shadow pciutils \
mkinitfs</pre>

=== Setup openrc services ===
<pre>for rc in boot/bootmisc boot/hostname boot/modules boot/sysctl boot/urandom boot/networking \
sysinit/devfs sysinit/hwdrivers sysinit/mdev sysinit/modules \
shutdown/mount-ro shutdown/killprocs \
default/dbus default/networking default/chronyd default/local; do
ln -s /etc/init.d/"${rc##*/}" /mnt/etc/runlevels/"$rc"
done</pre>

=== Setup fstab ===
<pre>cp /mnt/etc/fstab /mnt/etc/fstab.orig
echo $(blkid /dev/sdb2 | sed 's/.*: //;s/ .*//;s/"//g') / \ \ \ \ ext4 rw,relatime 0 1 > /mnt/etc/fstab.new
echo $(blkid /dev/sdb1 | sed 's/.*: //;s/ .*//;s/"//g') /boot ext4 rw,relatime 0 2 >> /mnt/etc/fstab.new
cat /mnt/etc/fstab.orig >> /mnt/etc/fstab.new
cp /mnt/etc/fstab.new /mnt/etc/fstab</pre>

=== Setup networking ===
<pre>[ ! -d /mnt/etc/network ] mkdir -vp /mnt/etc/networking
cat <<EOF > /mnt/etc/network/interfaces
auto lo
iface lo inet loopback

auto eth0
iface eth0 inet dhcp

EOF</pre>

=== Set the root password ===
When the system boots it will require a root password. This differs from Alpine install media but that's not the objective of this guide. This guide is installing a ready system.

<pre>passwd -R /mnt root</pre>

=== Enable login on UART ===
<pre>sed -i 's/^#ttyS0/ttyS0/' /mnt/etc/inittab</pre>

== Install Alpine from an non-Alpine RISC-V Linux host ==
This section is mainly intended for those trying to install Alpine from one of the vendor images or another RISCV64 install. The apk utility does need to be able to run post-build scripts in order for target installation to function properly.

=== Download a minirootfs to run apk within a chroot ===
<pre>cd /var/tmp
wget https://dl-cdn.alpinelinux.org/edge/releases/riscv64/alpine-minirootfs-20260127-riscv64.tar.gz</pre>
Unzip in /mnt
<pre>cd /mnt
tar xfpz /var/tmp/alpine-minirootfs-20260127-riscv64.tar.gz</pre>
{{Note|
If installing from a non-Alpine host, you may want to install the kernel image and modules first. Come back to this part to chroot and run the apk step and finish up with mkinitfs}}
Chroot into /mnt and run <code>apk add</code>
<pre>chroot /mnt /bin/sh
apk --arch riscv64 --allow-untrusted --initdb add \
alpine-base alpine-baselayout alpine-conf alpine-keys alpine-release alpine-baselayout-data \
kmod openrc dbus util-linux blkid chrony sysfsutils ssl_client openssh ca-certificates-bundle \
alpine-keys ethtool e2fsprogs e2fsprogs-extra libudev-zero libudev-zero-helper parted grep \
busybox-mdev-openrc procps-ng net-tools coreutils doas sed gawk findutils bash shadow pciutils \
mkinitfs</pre>

=== Setup openrc services ===
<pre>for rc in boot/bootmisc boot/hostname boot/modules boot/sysctl boot/urandom boot/networking \
sysinit/devfs sysinit/hwdrivers sysinit/mdev sysinit/modules \
shutdown/mount-ro shutdown/killprocs \
default/dbus default/networking default/chronyd default/local; do
ln -s /etc/init.d/"${rc##*/}" /etc/runlevels/"$rc"
done</pre>

=== Setup fstab within the chroot ===
<pre>cp /etc/fstab /etc/fstab.orig
echo $(blkid /dev/sdb2 | sed 's/.*: //;s/ .*//;s/"//g') / \ \ \ \ ext4 rw,relatime 0 1 > /etc/fstab.new
echo $(blkid /dev/sdb1 | sed 's/.*: //;s/ .*//;s/"//g') /boot ext4 rw,relatime 0 2 >> /etc/fstab.new
cat /etc/fstab.orig >> /etc/fstab.new
cp /etc/fstab.new /etc/fstab</pre>

=== Setup networking ===
<pre>[ ! -d /etc/network ] mkdir -vp /etc/networking
cat <<EOF > /etc/network/interfaces
auto lo
iface lo inet loopback

auto eth0
iface eth0 inet dhcp

EOF</pre>

=== Set the root password ===
When the system boots it will require a root password. This differs from Alpine install media but that's not the objective of this guide. This guide is installing a ready system.

<pre>passwd</pre>

=== Enable login on UART ===
<pre>sed -i 's/^#ttyS0/ttyS0/' /etc/inittab</pre>

== Setting up the boot environment ==
All of the effort up to this point has come down to this. This portion of the guide will assume the kernel being installed is version 6.6.63-ky from the vendor.
=== Install the kernel ===
We created an archive for each method of obtaining a kernel. Now we need to unpack that archive in our buildroot.
<pre>cd /mnt
tar xzf /var/tmp/linux-6.6.63-ky.tgz</pre>
=== Install the esos.elf firmware ===
Copy esos.elf from your very safe place to /mnt/lib/firmware
<pre>doas cp ~/Downloads/esos.elf /mnt/lib/firmware/</pre>
=== Creating the initrd image ===
The methods to obtain a kernel omitted collecting initrd images. Those images would not have been based on Alpine. We'll be using <code>mkinitfs</code> to do this. There are a few modifications we need to make in order for this process to generate an image with all the required bits.
==== Configuring and fixing mkinitfs ====
===== Add esos.elf to mkinitfs/features.d/base.files =====
<pre>echo "/lib/firmware/esos.elf" >> /etc/mkinitfs/features.d/base.files</pre>
===== Add the wireless-regdb database files to base.files =====
{{Note|
You may not need this. If you see a kernel message regarding failure to load regulatory.db with error -2, this will resolve it. Requires install of wireless-regdb apk package.}}
<pre>echo "/lib/firmware/regulatory.*" >> /etc/mkinitfs/features.d/base.files</pre>

===== Prevent mkinitfs from deleting needed firmware =====
The mkinitfs script will delete a directory that shouldn't exist. The files assembled from the features.d includes will have already been staged prior to mkinitfs assembling firmware needed by included modules. We need this not to happen and below is the simplest workaround I could pull together.
Make a copy of mkinitfs
<pre>cp /sbin/mkinitfs /sbin/mkinitfs-rv2</pre>
In the initfs_firmware function of <code>/sbin/mkinitfs-rv2</code> you will find the following lines
<pre> rm -rf "$tmpdir"/lib/firmware
mkdir -p "$tmpdir"/lib/firmware</pre>
Change them to be
<pre> #rm -rf "$tmpdir"/lib/firmware
[ ! -d "$tmpdir"/lib/firmware ] && mkdir -p "$tmpdir"/lib/firmware</pre>

==== Using mkinitfs-rv2 to create an initrd image ====
Installing from an Alpine host
<pre>mkinitfs-rv2 -b /mnt -c /mnt/etc/mkinitfs/mkinitfs.conf -o /mnt/boot/initramfs-6.6.63-ky 6.6.63-ky</pre>

Installing within a chroot
<pre>mkinitfs-rv2 -c /etc/mkinitfs/mkinitfs.conf -o /boot/initramfs-6.6.63-ky 6.6.63-ky</pre>
=== Configure extlinux ===
Create an extlinux.conf file with the following
<pre>default l0
menu title Alpine U-Boot menu
prompt 1
timeout 10

label l0
menu label Alpine Linux 3.24.0_alpha20260127 (Kernel 6.6.63-ky)
linux /vmlinuz-6.6.63-ky
initrd /initramfs-6.6.63-ky
fdt /dtb-6.6.63-ky/ky/x1_orangepi-rv2.dtb
append mtdparts=d420c000.spi-0:64K@0(bootinfo),64K@64K(private),256K@128K(fsbl),64K@384K(env),192K@448K(opensbi),-@640K(uboot) root=UUID=236a5824-0390-42dc-83e3-f02123188f96 console=ttyS0,115200 console=tty1 rootwait rw rootfstype=ext4 earlycon=sbi</pre>

==== A few notes on extlinux.conf ====
* Most device trees are generated in a dtbs/[kernel-version] directory.
* The vendor vmlinuz is a decompressed kernel image, though it shouldn't matter
* The mtdparts kernel parameter isn't absolutely required
* Only the right-most console statement seems to get attention. If you're on UART then you'll want <code>console=ttyS0,115200</code> and if you're on the framebuffer you'll want <code>console=tty1</code>.

== Wrapping Up ==

At this point the primary setup is complete. You may want to add some additional packages or configuration but can also be done after booting the RV2 board.

I may have forgotton something(s) which you'll soon discoven. I'll do my best to fold in corrections as I find they're needed or as new information becomes available.

=== Unmount the buildroot ===

<pre>umount /mnt/proc /mnt/sys /mnt/dev /mnt/boot /mnt</pre>

== Usability extras ==

The above should get your OrangePi RV2 booting Alpine Linux. Below are some additional configurations to help make growing your install a little easier. The following assumes you're still chroot /mnt or have booted the system.

=== Add a local user for yourself with escalation privileges ===

Create a user account for yourself with a secondary group of wheel
<pre># Create your account
useradd -G wheel -s /bin/bash -d /home/myuser -m -c "My User" myuser
# Set your password
passwd myuser</pre>

Add a configuration to doas.d for group wheel
<pre>echo permit persist :wheel > /etc/doas.d/00-wheel.conf</pre>

=== Install Avahi for mdns broadcasts ===

Avahi can broadcast names for services provided by your host. The default config in the Alpine package provides a configuration for sshd.

<pre># First setup the hostname
setup-hostname myhost

# Set the hostname
hostname `cat /etc/hostname`

# Install the avahi apk
apk add avahi

# Enable and start the avahi daemon
rc-update add avahi-daemon && rc-service avahi-daemon start</pre>

[[Category:Riscv64]]

Installing Alpine Linux on OrangePi RV2

2026-04-11T06:47:21Z

Aarch0x40:

{{Draft}}
[[Main Page]] > [[:Category:Architectures|Architectures]] > [[Riscv64]] > Installing Alpine Linux on OrangePi RV2
 
{{Warning|The contributors to the Alpine Linux project are not responsible for any damage/loss experienced by using the following guide. This article is provided as a general reference. It is assumed that the implementer will have the knowledge and ability to close the gap between what is described here and their specific setup.}}

The [http://www.orangepi.org/html/hardWare/computerAndMicrocontrollers/details/Orange-Pi-RV2.html OrangePi RV2] is a credit-card sized development board with a Ky X1 8-Core SoC. The Ky X1 is for all intents and purposes a SpacemiT K1 SoC. The remainder of this guide is more likely to use the terms SpacemiT or K1 as is prevalent throughout the Linux community. Please understand that these terms all refer to the same RISC-V ISA implementation.

This guide assumes that the manufacturer provided [https://github.com/riscv-software-src/opensbi OpenSBI] and [https://u-boot.org/ U-Boot] binaries have been applied to the SPI Flash device. This stock bootloader will look for an <code>extlinux/extlinux.conf</code> which will be used to configure the boot process.

Those following this guide may find it useful to have a USB UART serial cable available to debug kernel loading.

This guide borrows heavily from the article [https://arvanta.net/alpine/install-alpine-riscv64-qemu-uboot/ install Alpine Linux riscv64 under qemu with u-boot loader] by Milan P. Stanić and posted to [[Riscv64]] by [[User:AnIDFB]].

== Known issues ==
 
{{Warning|The following are the issues that are known to exist between the result of this guide and the manufacturer provided image}}

* Wireless (Wi-Fi & Bluetooth) is not functional
* Some kernel sources have an issue with starting the framebuffer
* Manufacturer tools are not included

This guide was assembled as a dumping of my personal notes. It's being updated as I come across new information. Alpine does run on the RV2 albeit not directly out of the box. Will do my best to reference external materials so that this article may provide some insight to others while still under development. The above may not be the only issues but hopefully there's enough information here to get you going.

== Kernel and Firmware ==
There are a few different options for kernels. The extent of coverage documented here is largely due to my initial ignorance. I have found a few sources for mostly workable kernels. None of them works 100%. SpacemiT is still in the process upstreaming functionality.

=== Obtaining the ESOS firmware ===
The processor being used on the RV2 requires a firmware to function properly. This file is available from the vendor images, in third party distributions and in the [https://github.com/orangepi-xunlong/orangepi-build orangepi-xunlong/orangepi-build] GitHub repository. The subdirectory containing the required file is [https://github.com/orangepi-xunlong/orangepi-build/tree/next/external/packages/bsp/ky/usr/lib/firmware external/packages/bsp/ky/usr/lib/firmware]. Download the file <code>esos.elf</code>. Keep the download in a safe place and also <code>/lib/firmware</code>. The <code>/lib/firmware</code> directory is also where you'll find this file within the vendor's image or an initrd image.
{{Note|
Changes to mkinitfs will be needed in order for this firmware to be included. More information on that will be provided further down the document}}

=== Why not the Alpine Kernel? ===
The kernels available from the Alpine Linux Project won't completely boot. U-Boot is able to load and run the kernel. The kernel is able to unpack the initramfs image and start the init process. The kernel panics though because the init process fails to mount a root filesystem. The init process is unable to mount a root filesystem because the kernel doesn't have the capability to load the esos.elf firmware. This capability is provided by the remoteproc driver. My experience with the RV2 so far shown that loading this firmware is required for enabling the full function of the K1/X1 SoC.

=== Obtaining the Vendor kernel ===
Open a browser to the [http://www.orangepi.org/html/hardWare/computerAndMicrocontrollers/service-and-support/Orange-Pi-RV2.html OrangePI RV2 Download] page.

Click on the "Downloads" button for the Ubuntu Image. This will take you to a Google Drive folder. Download the Orangepirv2_1.0.0_ubuntu_noble_server_linux6.6.63.7z.

Decompress this file after downloading using your favorite archive utility. It will expand to a directory containing Orangepirv2_1.0.0_ubuntu_noble_server_linux6.6.63.img and shasum file.

Attach the image to a loop device and mount the root partition.
<pre># Find the first available loop device
doas losetup --find

# Assuming the first found available device is /dev/loop0
doas losetup -P /dev/loop0 Orangepirv2_1.0.0_ubuntu_noble_server_linux6.6.63.img

# Mount the root slice
doas mount /dev/loop0p1 /mnt
</pre>

Archive the vendor kernel
<pre>cd /mnt
tar czf /var/tmp/linux-6.6.63-ky.tgz boot/vmlinuz-6.6.63-ky boot/System.map-6.6.63-ky boot/config-6.6.63-ky boot/dtb-6.6.63-ky lib/modules/6.6.63-ky</pre>
{{Note|
You probably want to put the resulting archive in a safer place than /var/tmp at this point. There's a bit to do before we'll need it.}}

Unmount and detach the vendor image
<pre>cd -
doas umount /mnt
doas losetup -d /dev/loop0</pre>
=== Building from source ===
There have been 2 main repositories for patched kernel sources.

* [https://github.com/jasonmontleon/linux-spacemit jasonmontleon/linux-spacemit]
* [https://github.com/BredOS/linux-bredos BredOS/linux-bredos]

The linux-spacemit repository is used by RedHat employee Jason Montleon in building out their RISCV64 support. The linux-bredos repository is used by the BredOS project which supports the RV2 and has provides downloadable images for the board. There is cross contribution between these two repositories. A lot of what I've learned to assemble this guide is attributed to these projects.

==== Setting up a workspace ====

Begin by setting up a RISC-V workspace by following [[Riscv64|Running Alpine riscv64 in QEMU]]. You'll need to establish a build environment in this QEMU guest.

<pre>doas apk add alpine-sdk bison flex openssl-dev ncurses ncurses-dev</pre>

{{Note|
<code>ncurses</code> and <code>ncurses-dev</code> aren't a hard requirements but are useful if you want to run <code>make menuconfig</code>}}

==== Cloning the source, configuring and building the kernel ====

{{Note|
This is needs a redo.}}

== Preparing the media ==

=== Partition and setup the filesystems ===
==== Install parted package ====
<pre>doas apk add parted</pre>
==== Insert, partition and format the boot media ====

The media can be either an SD card or USB drive. An 2280 PCIe NVMe is also possibly if you have the ability to write it from the host setting up the media. For the purposes of this guide we will refer to our boot media as <code>/dev/sdb</code>. The following section requires a root shell.

<pre>alias p="parted -sa optimal /dev/sdb"
p mklabel gpt
p mkpart boot ext4 0G 512M
p set 1 boot
p mkpart root ext4 512M 100%
p p</pre>

The final command should produce output to confirm the result of the executed commands. It should look something like the following.

<pre>Model: Generic STORAGE DEVICE (scsi)
Disk /dev/sdb: 15.5GB
Sector size (logical/physical): 512B/512B
Partition Table: gpt
Disk Flags:

Number Start End Size File system Name Flags
1 1049kB 512MB 511MB ext4 boot boot, esp
2 512MB 15.5GB 15.0GB root
</pre>

If all looks good, then we can proceed with formatting the partitions

<pre>mkfs.ext4 /dev/sdb1 && mkfs.ext4 /dev/sdb2</pre>

Mount the filesystems and lay some preliminary groundwork.

<pre># Mount the target root slice
mount /dev/sdb2 /mnt

# Create mount point for boot slice
[ ! -d /mnt/boot ] && mkdir -vp /mnt/boot

# Mount boot slice
mount /dev/sdb1 /mnt/boot

# Create directory for extlinux config
[ ! -d /mnt/boot/extlinux ] && mkdir -vp /mnt/boot/extlinux

# Create directory for apk config
[ ! -d /mnt/etc/apk ] && mkdir -vp /mnt/etc/apk

# Create mount point for devfs
[ ! -d /mnt/dev ] && mkdir -vp /mnt/dev

# Create mount point for procfs
[ ! -d /mnt/proc ] && mkdir -vp /mnt/proc

# Create mount point for sysfs
[ ! -d /mnt/sys ] && mkdir -vp /mnt/sys

# Use bind mounts for dev proc and sys within the target device
mount -o bind /dev /mnt/dev && mount -o bind /proc /mnt/proc && mount -o bind /sys /mnt/sys

# Configure apk package manager
cat <<EOF > /mnt/etc/apk/repositories
#/media/vda1/apks
http://dl-cdn.alpinelinux.org/alpine/edge/main
http://dl-cdn.alpinelinux.org/alpine/edge/community
http://dl-cdn.alpinelinux.org/alpine/edge/testing
EOF
</pre>
== Install Alpine from an Alpine host ==

=== Install Alpine with apk ===
Some of what is going to be installed is up to your choosing. This should be enough to get you going and demonstrate how to target an apk installation.
<pre>apk --root /mnt --arch riscv64 --allow-untrusted --initdb add \
alpine-base alpine-baselayout alpine-conf alpine-keys alpine-release alpine-baselayout-data \
kmod openrc dbus util-linux blkid chrony sysfsutils ssl_client openssh ca-certificates-bundle \
alpine-keys ethtool e2fsprogs e2fsprogs-extra libudev-zero libudev-zero-helper parted grep \
busybox-mdev-openrc procps-ng net-tools coreutils doas sed gawk findutils bash shadow pciutils \
mkinitfs</pre>

=== Setup openrc services ===
<pre>for rc in boot/bootmisc boot/hostname boot/modules boot/sysctl boot/urandom boot/networking \
sysinit/devfs sysinit/hwdrivers sysinit/mdev sysinit/modules \
shutdown/mount-ro shutdown/killprocs \
default/dbus default/networking default/chronyd default/local; do
ln -s /etc/init.d/"${rc##*/}" /mnt/etc/runlevels/"$rc"
done</pre>

=== Setup fstab ===
<pre>cp /mnt/etc/fstab /mnt/etc/fstab.orig
echo $(blkid /dev/sdb2 | sed 's/.*: //;s/ .*//;s/"//g') / \ \ \ \ ext4 rw,relatime 0 1 > /mnt/etc/fstab.new
echo $(blkid /dev/sdb1 | sed 's/.*: //;s/ .*//;s/"//g') /boot ext4 rw,relatime 0 2 >> /mnt/etc/fstab.new
cat /mnt/etc/fstab.orig >> /mnt/etc/fstab.new
cp /mnt/etc/fstab.new /mnt/etc/fstab</pre>

=== Setup networking ===
<pre>[ ! -d /mnt/etc/network ] mkdir -vp /mnt/etc/networking
cat <<EOF > /mnt/etc/network/interfaces
auto lo
iface lo inet loopback

auto eth0
iface eth0 inet dhcp

EOF</pre>

=== Set the root password ===
When the system boots it will require a root password. This differs from Alpine install media but that's not the objective of this guide. This guide is installing a ready system.

<pre>passwd -R /mnt root</pre>

=== Enable login on UART ===
<pre>sed -i 's/^#ttyS0/ttyS0/' /mnt/etc/inittab</pre>

== Install Alpine from an non-Alpine RISC-V Linux host ==
This section is mainly intended for those trying to install Alpine from one of the vendor images or another RISCV64 install. The apk utility does need to be able to run post-build scripts in order for target installation to function properly.

=== Download a minirootfs to run apk within a chroot ===
<pre>cd /var/tmp
wget https://dl-cdn.alpinelinux.org/edge/releases/riscv64/alpine-minirootfs-20260127-riscv64.tar.gz</pre>
Unzip in /mnt
<pre>cd /mnt
tar xfpz /var/tmp/alpine-minirootfs-20260127-riscv64.tar.gz</pre>
{{Note|
If installing from a non-Alpine host, you may want to install the kernel image and modules first. Come back to this part to chroot and run the apk step and finish up with mkinitfs}}
Chroot into /mnt and run <code>apk add</code>
<pre>chroot /mnt /bin/sh
apk --arch riscv64 --allow-untrusted --initdb add \
alpine-base alpine-baselayout alpine-conf alpine-keys alpine-release alpine-baselayout-data \
kmod openrc dbus util-linux blkid chrony sysfsutils ssl_client openssh ca-certificates-bundle \
alpine-keys ethtool e2fsprogs e2fsprogs-extra libudev-zero libudev-zero-helper parted grep \
busybox-mdev-openrc procps-ng net-tools coreutils doas sed gawk findutils bash shadow pciutils \
mkinitfs</pre>

=== Setup openrc services ===
<pre>for rc in boot/bootmisc boot/hostname boot/modules boot/sysctl boot/urandom boot/networking \
sysinit/devfs sysinit/hwdrivers sysinit/mdev sysinit/modules \
shutdown/mount-ro shutdown/killprocs \
default/dbus default/networking default/chronyd default/local; do
ln -s /etc/init.d/"${rc##*/}" /etc/runlevels/"$rc"
done</pre>

=== Setup fstab within the chroot ===
<pre>cp /etc/fstab /etc/fstab.orig
echo $(blkid /dev/sdb2 | sed 's/.*: //;s/ .*//;s/"//g') / \ \ \ \ ext4 rw,relatime 0 1 > /etc/fstab.new
echo $(blkid /dev/sdb1 | sed 's/.*: //;s/ .*//;s/"//g') /boot ext4 rw,relatime 0 2 >> /etc/fstab.new
cat /etc/fstab.orig >> /etc/fstab.new
cp /etc/fstab.new /etc/fstab</pre>

=== Setup networking ===
<pre>[ ! -d /etc/network ] mkdir -vp /etc/networking
cat <<EOF > /etc/network/interfaces
auto lo
iface lo inet loopback

auto eth0
iface eth0 inet dhcp

EOF</pre>

=== Set the root password ===
When the system boots it will require a root password. This differs from Alpine install media but that's not the objective of this guide. This guide is installing a ready system.

<pre>passwd</pre>

=== Enable login on UART ===
<pre>sed -i 's/^#ttyS0/ttyS0/' /etc/inittab</pre>

== Setting up the boot environment ==
All of the effort up to this point has come down to this. This portion of the guide will assume the kernel being installed is version 6.6.63-ky from the vendor.
=== Install the kernel ===
We created an archive for each method of obtaining a kernel. Now we need to unpack that archive in our buildroot.
<pre>cd /mnt
tar xzf /var/tmp/linux-6.6.63-ky.tgz</pre>
=== Install the esos.elf firmware ===
Copy esos.elf from your very safe place to /mnt/lib/firmware
<pre>doas cp ~/Downloads/esos.elf /mnt/lib/firmware/</pre>
=== Creating the initrd image ===
The methods to obtain a kernel omitted collecting initrd images. Those images would not have been based on Alpine. We'll be using <code>mkinitfs</code> to do this. There are a few modifications we need to make in order for this process to generate an image with all the required bits.
==== Configuring and fixing mkinitfs ====
===== Add esos.elf to mkinitfs/features.d/base.files =====
<pre>echo "/lib/firmware/esos.elf" >> /etc/mkinitfs/features.d/base.files</pre>
===== Add the wireless-regdb database files to base.files =====
{{Note|
You may not need this. If you see a kernel message regarding failure to load regulatory.db with error -2, this will resolve it. Requires install of wireless-regdb apk package.}}
<pre>echo "/lib/firmware/regulatory.*" >> /etc/mkinitfs/features.d/base.files</pre>

===== Prevent mkinitfs from deleting needed firmware =====
The mkinitfs script will delete a directory that shouldn't exist. The files assembled from the features.d includes will have already been staged prior to mkinitfs assembling firmware needed by included modules. We need this not to happen and below is the simplest workaround I could pull together.
Make a copy of mkinitfs
<pre>cp /sbin/mkinitfs /sbin/mkinitfs-rv2</pre>
In the initfs_firmware function of <code>/sbin/mkinitfs-rv2</code> you will find the following lines
<pre> rm -rf "$tmpdir"/lib/firmware
mkdir -p "$tmpdir"/lib/firmware</pre>
Change them to be
<pre> #rm -rf "$tmpdir"/lib/firmware
[ ! -d "$tmpdir"/lib/firmware ] && mkdir -p "$tmpdir"/lib/firmware</pre>

==== Using mkinitfs-rv2 to create an initrd image ====
Installing from an Alpine host
<pre>mkinitfs-rv2 -b /mnt -c /mnt/etc/mkinitfs/mkinitfs.conf -o /mnt/boot/initramfs-6.6.63-ky 6.6.63-ky</pre>

Installing within a chroot
<pre>mkinitfs-rv2 -c /etc/mkinitfs/mkinitfs.conf -o /boot/initramfs-6.6.63-ky 6.6.63-ky</pre>
=== Configure extlinux ===
Create an extlinux.conf file with the following
<pre>default l0
menu title Alpine U-Boot menu
prompt 1
timeout 10

label l0
menu label Alpine Linux 3.24.0_alpha20260127 (Kernel 6.6.63-ky)
linux /vmlinuz-6.6.63-ky
initrd /initramfs-6.6.63-ky
fdt /dtb-6.6.63-ky/ky/x1_orangepi-rv2.dtb
append mtdparts=d420c000.spi-0:64K@0(bootinfo),64K@64K(private),256K@128K(fsbl),64K@384K(env),192K@448K(opensbi),-@640K(uboot) root=UUID=236a5824-0390-42dc-83e3-f02123188f96 console=ttyS0,115200 console=tty1 rootwait rw rootfstype=ext4 earlycon=sbi</pre>

==== A few notes on extlinux.conf ====
* Most device trees are generated in a dtbs/[kernel-version] directory.
* The vendor vmlinuz is a decompressed kernel image, though it shouldn't matter
* The mtdparts kernel parameter isn't absolutely required
* Only the right-most console statement seems to get attention. If you're on UART then you'll want <code>console=ttyS0,115200</code> and if you're on the framebuffer you'll want <code>console=tty1</code>.

== Wrapping Up ==

At this point the primary setup is complete. You may want to add some additional packages or configuration but can also be done after booting the RV2 board.

I may have forgotton something(s) which you'll soon discoven. I'll do my best to fold in corrections as I find they're needed or as new information becomes available.

=== Unmount the buildroot ===

<pre>umount /mnt/proc /mnt/sys /mnt/dev /mnt/boot /mnt</pre>

== Usability extras ==

The above should get your OrangePi RV2 booting Alpine Linux. Below are some additional configurations to help make growing your install a little easier. The following assumes you're still chroot /mnt or have booted the system.

=== Add a local user for yourself with escalation privileges ===

Create a user account for yourself with a secondary group of wheel
<pre># Create your account
useradd -G wheel -s /bin/bash -d /home/myuser -m -c "My User" myuser
# Set your password
passwd myuser</pre>

Add a configuration to doas.d for group wheel
<pre>echo permit persist :wheel > /etc/doas.d/00-wheel.conf</pre>

=== Install Avahi for mdns broadcasts ===

Avahi can broadcast names for services provided by your host. The default config in the Alpine package provides a configuration for sshd.

<pre># First setup the hostname
setup-hostname myhost

# Set the hostname
hostname `cat /etc/hostname`

# Install the avahi apk
apk add avahi

# Enable and start the avahi daemon
rc-update add avahi-daemon && rc-service avahi-daemon start</pre>

[[Category:Riscv64]]

Installing Alpine Linux on OrangePi RV2

2026-04-11T05:37:51Z

Aarch0x40:

{{Draft}}
[[Main Page]] > [[:Category:Architectures|Architectures]] > [[Riscv64]] > Installing Alpine Linux on OrangePi RV2
 
{{Warning|The contributors to the Alpine Linux project are not responsible for any damage/loss experienced by using the following guide. This article is provided as a general reference. It is assumed that the implementer will have the knowledge and ability to close the gap between what is described here and their specific setup.}}

The [http://www.orangepi.org/html/hardWare/computerAndMicrocontrollers/details/Orange-Pi-RV2.html OrangePi RV2] is a credit-card sized development board with a Ky X1 8-Core SoC. The Ky X1 is for all intents and purposes a SpacemiT K1 SoC. The remainder of this guide is more likely to use the terms SpacemiT or K1 as is prevalent throughout the Linux community. Please understand that these terms all refer to the same RISC-V ISA implementation.

This guide assumes that the manufacturer provided [https://github.com/riscv-software-src/opensbi OpenSBI] and [https://u-boot.org/ U-Boot] binaries have been applied to the SPI Flash device. This stock bootloader will look for an <code>extlinux/extlinux.conf</code> which will be used to configure the boot process.

Those following this guide may find it useful to have a USB UART serial cable available to debug kernel loading.

This guide borrows heavily from the article [https://arvanta.net/alpine/install-alpine-riscv64-qemu-uboot/ install Alpine Linux riscv64 under qemu with u-boot loader] by Milan P. Stanić and posted to [[Riscv64]] by [[User:AnIDFB]].

== Known issues ==
 
{{Warning|The following are the issues that are known to exist between the result of this guide and the manufacturer provided image}}

* Wireless (Wi-Fi & Bluetooth) is not functional
* Some kernel sources have an issue with starting the framebuffer
* Manufacturer tools are not included

This guide was assembled as a dumping of my personal notes. It's being updated as I come across new information. Alpine does run on the RV2 albeit not directly out of the box. Will do my best to reference external materials so that this article may provide some insight to others while still under development. The above may not be the only issues but hopefully there's enough information here to get you going.

== Kernel and Firmware ==
There are a few different options for kernels. The extent of coverage documented here is largely due to my initial ignorance. I have found a few sources for mostly workable kernels. None of them works 100%. SpacemiT is still in the process upstreaming functionality.

=== Obtaining the ESOS firmware ===
The processor being used on the RV2 requires a firmware to function properly. This file is available from the vendor images, in third party distributions and in the [https://github.com/orangepi-xunlong/orangepi-build orangepi-xunlong/orangepi-build] GitHub repository. The subdirectory containing the required file is [https://github.com/orangepi-xunlong/orangepi-build/tree/next/external/packages/bsp/ky/usr/lib/firmware external/packages/bsp/ky/usr/lib/firmware]. Download the file <code>esos.elf</code>. Keep the download in a safe place and also <code>/lib/firmware</code>. The <code>/lib/firmware</code> directory is also where you'll find this file within the vendor's image or an initrd image.
{{Note|
Changes to mkinitfs will be needed in order for this firmware to be included. More information on that will be provided further down the document}}
=== Obtaining the Vendor kernel ===
Open a browser to the [http://www.orangepi.org/html/hardWare/computerAndMicrocontrollers/service-and-support/Orange-Pi-RV2.html OrangePI RV2 Download] page.

Click on the "Downloads" button for the Ubuntu Image. This will take you to a Google Drive folder. Download the Orangepirv2_1.0.0_ubuntu_noble_server_linux6.6.63.7z.

Decompress this file after downloading using your favorite archive utility. It will expand to a directory containing Orangepirv2_1.0.0_ubuntu_noble_server_linux6.6.63.img and shasum file.

Attach the image to a loop device and mount the root partition.
<pre># Find the first available loop device
doas losetup --find

# Assuming the first found available device is /dev/loop0
doas losetup -P /dev/loop0 Orangepirv2_1.0.0_ubuntu_noble_server_linux6.6.63.img

# Mount the root slice
doas mount /dev/loop0p1 /mnt
</pre>

Archive the vendor kernel
<pre>cd /mnt
tar czf /var/tmp/linux-6.6.63-ky.tgz boot/vmlinuz-6.6.63-ky boot/System.map-6.6.63-ky boot/config-6.6.63-ky boot/dtb-6.6.63-ky lib/modules/6.6.63-ky</pre>
{{Note|
You probably want to put the resulting archive in a safer place than /var/tmp at this point. There's a bit to do before we'll need it.}}

Unmount and detach the vendor image
<pre>cd -
doas umount /mnt
doas losetup -d /dev/loop0</pre>
=== Will Alpine's kernel work? (TBD) ===
{{Note|
Need to revisit this}}
=== Building from source ===
There have been 2 main repositories for patched kernel sources.

* [https://github.com/jasonmontleon/linux-spacemit jasonmontleon/linux-spacemit]
* [https://github.com/BredOS/linux-bredos BredOS/linux-bredos]

The linux-spacemit repository is used by RedHat employee Jason Montleon in building out their RISCV64 support. The linux-bredos repository is used by the BredOS project which supports the RV2 and has provides downloadable images for the board. There is cross contribution between these two repositories. A lot of what I've learned to assemble this guide is attributed to these projects.

==== Setting up a workspace ====

Begin by setting up a RISC-V workspace by following [[Riscv64|Running Alpine riscv64 in QEMU]]. You'll need to establish a build environment in this QEMU guest.

<pre>doas apk add alpine-sdk bison flex openssl-dev ncurses ncurses-dev</pre>

{{Note|
<code>ncurses</code> and <code>ncurses-dev</code> aren't a hard requirements but are useful if you want to run <code>make menuconfig</code>}}

==== Cloning the source, configuring and building the kernel ====

{{Note|
This is needs a redo.}}

== Preparing the media ==

=== Partition and setup the filesystems ===
==== Install parted package ====
<pre>doas apk add parted</pre>
==== Insert, partition and format the boot media ====

The media can be either an SD card or USB drive. An 2280 PCIe NVMe is also possibly if you have the ability to write it from the host setting up the media. For the purposes of this guide we will refer to our boot media as <code>/dev/sdb</code>. The following section requires a root shell.

<pre>alias p="parted -sa optimal /dev/sdb"
p mklabel gpt
p mkpart boot ext4 0G 512M
p set 1 boot
p mkpart root ext4 512M 100%
p p</pre>

The final command should produce output to confirm the result of the executed commands. It should look something like the following.

<pre>Model: Generic STORAGE DEVICE (scsi)
Disk /dev/sdb: 15.5GB
Sector size (logical/physical): 512B/512B
Partition Table: gpt
Disk Flags:

Number Start End Size File system Name Flags
1 1049kB 512MB 511MB ext4 boot boot, esp
2 512MB 15.5GB 15.0GB root
</pre>

If all looks good, then we can proceed with formatting the partitions

<pre>mkfs.ext4 /dev/sdb1 && mkfs.ext4 /dev/sdb2</pre>

Mount the filesystems and lay some preliminary groundwork.

<pre># Mount the target root slice
mount /dev/sdb2 /mnt

# Create mount point for boot slice
[ ! -d /mnt/boot ] && mkdir -vp /mnt/boot

# Mount boot slice
mount /dev/sdb1 /mnt/boot

# Create directory for extlinux config
[ ! -d /mnt/boot/extlinux ] && mkdir -vp /mnt/boot/extlinux

# Create directory for apk config
[ ! -d /mnt/etc/apk ] && mkdir -vp /mnt/etc/apk

# Create mount point for devfs
[ ! -d /mnt/dev ] && mkdir -vp /mnt/dev

# Create mount point for procfs
[ ! -d /mnt/proc ] && mkdir -vp /mnt/proc

# Create mount point for sysfs
[ ! -d /mnt/sys ] && mkdir -vp /mnt/sys

# Use bind mounts for dev proc and sys within the target device
mount -o bind /dev /mnt/dev && mount -o bind /proc /mnt/proc && mount -o bind /sys /mnt/sys

# Configure apk package manager
cat <<EOF > /mnt/etc/apk/repositories
#/media/vda1/apks
http://dl-cdn.alpinelinux.org/alpine/edge/main
http://dl-cdn.alpinelinux.org/alpine/edge/community
http://dl-cdn.alpinelinux.org/alpine/edge/testing
EOF
</pre>
== Install Alpine from an Alpine host ==

=== Install Alpine with apk ===
Some of what is going to be installed is up to your choosing. This should be enough to get you going and demonstrate how to target an apk installation.
<pre>apk --root /mnt --arch riscv64 --allow-untrusted --initdb add \
alpine-base alpine-baselayout alpine-conf alpine-keys alpine-release alpine-baselayout-data \
kmod openrc dbus util-linux blkid chrony sysfsutils ssl_client openssh ca-certificates-bundle \
alpine-keys ethtool e2fsprogs e2fsprogs-extra libudev-zero libudev-zero-helper parted grep \
busybox-mdev-openrc procps-ng net-tools coreutils doas sed gawk findutils bash shadow pciutils \
mkinitfs</pre>

=== Setup openrc services ===
<pre>for rc in boot/bootmisc boot/hostname boot/modules boot/sysctl boot/urandom boot/networking \
sysinit/devfs sysinit/hwdrivers sysinit/mdev sysinit/modules \
shutdown/mount-ro shutdown/killprocs \
default/dbus default/networking default/chronyd default/local; do
ln -s /etc/init.d/"${rc##*/}" /mnt/etc/runlevels/"$rc"
done</pre>

=== Setup fstab ===
<pre>cp /mnt/etc/fstab /mnt/etc/fstab.orig
echo $(blkid /dev/sdb2 | sed 's/.*: //;s/ .*//;s/"//g') / \ \ \ \ ext4 rw,relatime 0 1 > /mnt/etc/fstab.new
echo $(blkid /dev/sdb1 | sed 's/.*: //;s/ .*//;s/"//g') /boot ext4 rw,relatime 0 2 >> /mnt/etc/fstab.new
cat /mnt/etc/fstab.orig >> /mnt/etc/fstab.new
cp /mnt/etc/fstab.new /mnt/etc/fstab</pre>

=== Setup networking ===
<pre>[ ! -d /mnt/etc/network ] mkdir -vp /mnt/etc/networking
cat <<EOF > /mnt/etc/network/interfaces
auto lo
iface lo inet loopback

auto eth0
iface eth0 inet dhcp

EOF</pre>

=== Set the root password ===
When the system boots it will require a root password. This differs from Alpine install media but that's not the objective of this guide. This guide is installing a ready system.

<pre>passwd -R /mnt root</pre>

=== Enable login on UART ===
<pre>sed -i 's/^#ttyS0/ttyS0/' /mnt/etc/inittab</pre>

== Install Alpine from an non-Alpine RISC-V Linux host ==
This section is mainly intended for those trying to install Alpine from one of the vendor images or another RISCV64 install. The apk utility does need to be able to run post-build scripts in order for target installation to function properly.

=== Download a minirootfs to run apk within a chroot ===
<pre>cd /var/tmp
wget https://dl-cdn.alpinelinux.org/edge/releases/riscv64/alpine-minirootfs-20260127-riscv64.tar.gz</pre>
Unzip in /mnt
<pre>cd /mnt
tar xfpz /var/tmp/alpine-minirootfs-20260127-riscv64.tar.gz</pre>
{{Note|
If installing from a non-Alpine host, you may want to install the kernel image and modules first. Come back to this part to chroot and run the apk step and finish up with mkinitfs}}
Chroot into /mnt and run <code>apk add</code>
<pre>chroot /mnt /bin/sh
apk --arch riscv64 --allow-untrusted --initdb add \
alpine-base alpine-baselayout alpine-conf alpine-keys alpine-release alpine-baselayout-data \
kmod openrc dbus util-linux blkid chrony sysfsutils ssl_client openssh ca-certificates-bundle \
alpine-keys ethtool e2fsprogs e2fsprogs-extra libudev-zero libudev-zero-helper parted grep \
busybox-mdev-openrc procps-ng net-tools coreutils doas sed gawk findutils bash shadow pciutils \
mkinitfs</pre>

=== Setup openrc services ===
<pre>for rc in boot/bootmisc boot/hostname boot/modules boot/sysctl boot/urandom boot/networking \
sysinit/devfs sysinit/hwdrivers sysinit/mdev sysinit/modules \
shutdown/mount-ro shutdown/killprocs \
default/dbus default/networking default/chronyd default/local; do
ln -s /etc/init.d/"${rc##*/}" /etc/runlevels/"$rc"
done</pre>

=== Setup fstab within the chroot ===
<pre>cp /etc/fstab /etc/fstab.orig
echo $(blkid /dev/sdb2 | sed 's/.*: //;s/ .*//;s/"//g') / \ \ \ \ ext4 rw,relatime 0 1 > /etc/fstab.new
echo $(blkid /dev/sdb1 | sed 's/.*: //;s/ .*//;s/"//g') /boot ext4 rw,relatime 0 2 >> /etc/fstab.new
cat /etc/fstab.orig >> /etc/fstab.new
cp /etc/fstab.new /etc/fstab</pre>

=== Setup networking ===
<pre>[ ! -d /etc/network ] mkdir -vp /etc/networking
cat <<EOF > /etc/network/interfaces
auto lo
iface lo inet loopback

auto eth0
iface eth0 inet dhcp

EOF</pre>

=== Set the root password ===
When the system boots it will require a root password. This differs from Alpine install media but that's not the objective of this guide. This guide is installing a ready system.

<pre>passwd</pre>

=== Enable login on UART ===
<pre>sed -i 's/^#ttyS0/ttyS0/' /etc/inittab</pre>

== Setting up the boot environment ==
All of the effort up to this point has come down to this. This portion of the guide will assume the kernel being installed is version 6.6.63-ky from the vendor.
=== Install the kernel ===
We created an archive for each method of obtaining a kernel. Now we need to unpack that archive in our buildroot.
<pre>cd /mnt
tar xzf /var/tmp/linux-6.6.63-ky.tgz</pre>
=== Install the esos.elf firmware ===
Copy esos.elf from your very safe place to /mnt/lib/firmware
<pre>doas cp ~/Downloads/esos.elf /mnt/lib/firmware/</pre>
=== Creating the initrd image ===
The methods to obtain a kernel omitted collecting initrd images. Those images would not have been based on Alpine. We'll be using <code>mkinitfs</code> to do this. There are a few modifications we need to make in order for this process to generate an image with all the required bits.
==== Configuring and fixing mkinitfs ====
===== Add esos.elf to mkinitfs/features.d/base.files =====
<pre>echo "/lib/firmware/esos.elf" >> /etc/mkinitfs/features.d/base.files</pre>
===== Add the wireless-regdb database files to base.files =====
{{Note|
You may not need this. If you see a kernel message regarding failure to load regulatory.db with error -2, this will resolve it. Requires install of wireless-regdb apk package.}}
<pre>echo "/lib/firmware/regulatory.*" >> /etc/mkinitfs/features.d/base.files</pre>

===== Prevent mkinitfs from deleting needed firmware =====
The mkinitfs script will delete a directory that shouldn't exist. The files assembled from the features.d includes will have already been staged prior to mkinitfs assembling firmware needed by included modules. We need this not to happen and below is the simplest workaround I could pull together.
Make a copy of mkinitfs
<pre>cp /sbin/mkinitfs /sbin/mkinitfs-rv2</pre>
In the initfs_firmware function of <code>/sbin/mkinitfs-rv2</code> you will find the following lines
<pre> rm -rf "$tmpdir"/lib/firmware
mkdir -p "$tmpdir"/lib/firmware</pre>
Change them to be
<pre> #rm -rf "$tmpdir"/lib/firmware
[ ! -d "$tmpdir"/lib/firmware ] && mkdir -p "$tmpdir"/lib/firmware</pre>

==== Using mkinitfs-rv2 to create an initrd image ====
Installing from an Alpine host
<pre>mkinitfs-rv2 -b /mnt -c /mnt/etc/mkinitfs/mkinitfs.conf -o /mnt/boot/initramfs-6.6.63-ky 6.6.63-ky</pre>

Installing within a chroot
<pre>mkinitfs-rv2 -c /etc/mkinitfs/mkinitfs.conf -o /boot/initramfs-6.6.63-ky 6.6.63-ky</pre>
=== Configure extlinux ===
Create an extlinux.conf file with the following
<pre>default l0
menu title Alpine U-Boot menu
prompt 1
timeout 10

label l0
menu label Alpine Linux 3.24.0_alpha20260127 (Kernel 6.6.63-ky)
linux /vmlinuz-6.6.63-ky
initrd /initramfs-6.6.63-ky
fdt /dtb-6.6.63-ky/ky/x1_orangepi-rv2.dtb
append mtdparts=d420c000.spi-0:64K@0(bootinfo),64K@64K(private),256K@128K(fsbl),64K@384K(env),192K@448K(opensbi),-@640K(uboot) root=UUID=236a5824-0390-42dc-83e3-f02123188f96 console=ttyS0,115200 console=tty1 rootwait rw rootfstype=ext4 earlycon=sbi</pre>

==== A few notes on extlinux.conf ====
* Most device trees are generated in a dtbs/[kernel-version] directory.
* The vendor vmlinuz is a decompressed kernel image, though it shouldn't matter
* The mtdparts kernel parameter isn't absolutely required
* Only the right-most console statement seems to get attention. If you're on UART then you'll want <code>console=ttyS0,115200</code> and if you're on the framebuffer you'll want <code>console=tty1</code>.

== Wrapping Up ==

At this point the primary setup is complete. You may want to add some additional packages or configuration but can also be done after booting the RV2 board.

I may have forgotton something(s) which you'll soon discoven. I'll do my best to fold in corrections as I find they're needed or as new information becomes available.

=== Unmount the buildroot ===

<pre>umount /mnt/proc /mnt/sys /mnt/dev /mnt/boot /mnt</pre>

== Usability extras ==

The above should get your OrangePi RV2 booting Alpine Linux. Below are some additional configurations to help make growing your install a little easier. The following assumes you're still chroot /mnt or have booted the system.

=== Add a local user for yourself with escalation privileges ===

Create a user account for yourself with a secondary group of wheel
<pre># Create your account
useradd -G wheel -s /bin/bash -d /home/myuser -m -c "My User" myuser
# Set your password
passwd myuser</pre>

Add a configuration to doas.d for group wheel
<pre>echo permit persist :wheel > /etc/doas.d/00-wheel.conf</pre>

=== Install Avahi for mdns broadcasts ===

Avahi can broadcast names for services provided by your host. The default config in the Alpine package provides a configuration for sshd.

<pre># First setup the hostname
setup-hostname myhost

# Set the hostname
hostname `cat /etc/hostname`

# Install the avahi apk
apk add avahi

# Enable and start the avahi daemon
rc-update add avahi-daemon && rc-service avahi-daemon start</pre>

[[Category:Riscv64]]

Installing Alpine Linux on OrangePi RV2

2026-04-11T05:33:56Z

Aarch0x40: /* Add jdb2 to ext4 */

{{Draft}}
[[Main Page]] > [[:Category:Architectures|Architectures]] > [[Riscv64]] > Installing Alpine Linux on OrangePi RV2
 
{{Warning|The contributors to the Alpine Linux project are not responsible for any damage/loss experienced by using the following guide. This article is provided as a general reference. It is assumed that the implementer will have the knowledge and ability to close the gap between what is described here and their specific setup.}}

The [http://www.orangepi.org/html/hardWare/computerAndMicrocontrollers/details/Orange-Pi-RV2.html OrangePi RV2] is a credit-card sized development board with a Ky X1 8-Core SoC. The Ky X1 is for all intents and purposes a SpacemiT K1 SoC. The remainder of this guide is more likely to use the terms SpacemiT or K1 as is prevalent throughout the Linux community. Please understand that these terms all refer to the same RISC-V ISA implementation.

This guide assumes that the manufacturer provided [https://github.com/riscv-software-src/opensbi OpenSBI] and [https://u-boot.org/ U-Boot] binaries have been applied to the SPI Flash device. This stock bootloader will look for an <code>extlinux/extlinux.conf</code> which will be used to configure the boot process.

Those following this guide may find it useful to have a USB UART serial cable available to debug kernel loading.

This guide borrows heavily from the article [https://arvanta.net/alpine/install-alpine-riscv64-qemu-uboot/ install Alpine Linux riscv64 under qemu with u-boot loader] by Milan P. Stanić and posted to [[Riscv64]] by [[User:AnIDFB]].

== Known issues ==
 
{{Warning|The following are the issues that are known to exist between the result of this guide and the manufacturer provided image}}

* Wireless (Wi-Fi & Bluetooth) is not functional
* Some kernel sources have an issue with starting the framebuffer
* Manufacturer tools are not included

This guide was assembled as a dumping of my personal notes. It's being updated as I come across new information. Alpine does run on the RV2 albeit not directly out of the box. Will do my best to reference external materials so that this article may provide some insight to others while still under development. The above may not be the only issues but hopefully there's enough information here to get you going.

== Kernel and Firmware ==
There are a few different options for kernels. The extent of coverage documented here is largely due to my initial ignorance. I have found a few sources for mostly workable kernels. None of them works 100%. SpacemiT is still in the process upstreaming functionality.

=== Obtaining the ESOS firmware ===
The processor being used on the RV2 requires a firmware to function properly. This file is available from the vendor images, in third party distributions and in the [https://github.com/orangepi-xunlong/orangepi-build orangepi-xunlong/orangepi-build] GitHub repository. The subdirectory containing the required file is [https://github.com/orangepi-xunlong/orangepi-build/tree/next/external/packages/bsp/ky/usr/lib/firmware external/packages/bsp/ky/usr/lib/firmware]. Download the file <code>esos.elf</code>. Keep the download in a safe place and also <code>/lib/firmware</code>. The <code>/lib/firmware</code> directory is also where you'll find this file within the vendor's image or an initrd image.
{{Note|
Changes to mkinitfs will be needed in order for this firmware to be included. More information on that will be provided further down the document}}
=== Obtaining the Vendor kernel ===
Open a browser to the [http://www.orangepi.org/html/hardWare/computerAndMicrocontrollers/service-and-support/Orange-Pi-RV2.html OrangePI RV2 Download] page.

Click on the "Downloads" button for the Ubuntu Image. This will take you to a Google Drive folder. Download the Orangepirv2_1.0.0_ubuntu_noble_server_linux6.6.63.7z.

Decompress this file after downloading using your favorite archive utility. It will expand to a directory containing Orangepirv2_1.0.0_ubuntu_noble_server_linux6.6.63.img and shasum file.

Attach the image to a loop device and mount the root partition.
<pre># Find the first available loop device
doas losetup --find

# Assuming the first found available device is /dev/loop0
doas losetup -P /dev/loop0 Orangepirv2_1.0.0_ubuntu_noble_server_linux6.6.63.img

# Mount the root slice
doas mount /dev/loop0p1 /mnt
</pre>

Archive the vendor kernel
<pre>cd /mnt
tar czf /var/tmp/linux-6.6.63-ky.tgz boot/vmlinuz-6.6.63-ky boot/System.map-6.6.63-ky boot/config-6.6.63-ky boot/dtb-6.6.63-ky lib/modules/6.6.63-ky</pre>
{{Note|
You probably want to put the resulting archive in a safer place than /var/tmp at this point. There's a bit to do before we'll need it.}}

Unmount and detach the vendor image
<pre>cd -
doas umount /mnt
doas losetup -d /dev/loop0</pre>
=== Will Alpine's kernel work? (TBD) ===
{{Note|
Need to revisit this}}
=== Building from source ===
There have been 2 main repositories for patched kernel sources.

* [https://github.com/jasonmontleon/linux-spacemit jasonmontleon/linux-spacemit]
* [https://github.com/BredOS/linux-bredos BredOS/linux-bredos]

The linux-spacemit repository is used by RedHat employee Jason Montleon in building out their RISCV64 support. The linux-bredos repository is used by the BredOS project which supports the RV2 and has provides downloadable images for the board. There is cross contribution between these two repositories. A lot of what I've learned to assemble this guide is attributed to these projects.

==== Setting up a workspace ====

Begin by setting up a RISC-V workspace by following [[Riscv64|Running Alpine riscv64 in QEMU]]. You'll need to establish a build environment in this QEMU guest.

<pre>doas apk add alpine-sdk bison flex openssl-dev ncurses ncurses-dev</pre>

{{Note|
<code>ncurses</code> and <code>ncurses-dev</code> aren't a hard requirements but are useful if you want to run <code>make menuconfig</code>}}

==== Cloning the source, configuring and building the kernel ====

{{Note|
This is needs a redo.}}

== Preparing the media ==

=== Partition and setup the filesystems ===
==== Install parted package ====
<pre>doas apk add parted</pre>
==== Insert, partition and format the boot media ====

The media can be either an SD card or USB drive. An 2280 PCIe NVMe is also possibly if you have the ability to write it from the host setting up the media. For the purposes of this guide we will refer to our boot media as <code>/dev/sdb</code>. The following section requires a root shell.

<pre>alias p="parted -sa optimal /dev/sdb"
p mklabel gpt
p mkpart boot ext4 0G 512M
p set 1 boot
p mkpart root ext4 512M 100%
p p</pre>

The final command should produce output to confirm the result of the executed commands. It should look something like the following.

<pre>Model: Generic STORAGE DEVICE (scsi)
Disk /dev/sdb: 15.5GB
Sector size (logical/physical): 512B/512B
Partition Table: gpt
Disk Flags:

Number Start End Size File system Name Flags
1 1049kB 512MB 511MB ext4 boot boot, esp
2 512MB 15.5GB 15.0GB root
</pre>

If all looks good, then we can proceed with formatting the partitions

<pre>mkfs.ext4 /dev/sdb1 && mkfs.ext4 /dev/sdb2</pre>

Mount the filesystems and lay some preliminary groundwork.

<pre># Mount the target root slice
mount /dev/sdb2 /mnt

# Create mount point for boot slice
[ ! -d /mnt/boot ] && mkdir -vp /mnt/boot

# Mount boot slice
mount /dev/sdb1 /mnt/boot

# Create directory for extlinux config
[ ! -d /mnt/boot/extlinux ] && mkdir -vp /mnt/boot/extlinux

# Create directory for apk config
[ ! -d /mnt/etc/apk ] && mkdir -vp /mnt/etc/apk

# Create mount point for devfs
[ ! -d /mnt/dev ] && mkdir -vp /mnt/dev

# Create mount point for procfs
[ ! -d /mnt/proc ] && mkdir -vp /mnt/proc

# Create mount point for sysfs
[ ! -d /mnt/sys ] && mkdir -vp /mnt/sys

# Use bind mounts for dev proc and sys within the target device
mount -o bind /dev /mnt/dev && mount -o bind /proc /mnt/proc && mount -o bind /sys /mnt/sys

# Configure apk package manager
cat <<EOF > /mnt/etc/apk/repositories
#/media/vda1/apks
http://dl-cdn.alpinelinux.org/alpine/edge/main
http://dl-cdn.alpinelinux.org/alpine/edge/community
http://dl-cdn.alpinelinux.org/alpine/edge/testing
EOF
</pre>
== Install Alpine from an Alpine host ==

=== Install Alpine with apk ===
Some of what is going to be installed is up to your choosing. This should be enough to get you going and demonstrate how to target an apk installation.
<pre>apk --root /mnt --arch riscv64 --allow-untrusted --initdb add \
alpine-base alpine-baselayout alpine-conf alpine-keys alpine-release alpine-baselayout-data \
kmod openrc dbus util-linux blkid chrony sysfsutils ssl_client openssh ca-certificates-bundle \
alpine-keys ethtool e2fsprogs e2fsprogs-extra libudev-zero libudev-zero-helper parted grep \
busybox-mdev-openrc procps-ng net-tools coreutils doas sed gawk findutils bash shadow pciutils \
mkinitfs</pre>

=== Setup openrc services ===
<pre>for rc in boot/bootmisc boot/hostname boot/modules boot/sysctl boot/urandom boot/networking \
sysinit/devfs sysinit/hwdrivers sysinit/mdev sysinit/modules \
shutdown/mount-ro shutdown/killprocs \
default/dbus default/networking default/chronyd default/local; do
ln -s /etc/init.d/"${rc##*/}" /mnt/etc/runlevels/"$rc"
done</pre>

=== Setup fstab ===
<pre>cp /mnt/etc/fstab /mnt/etc/fstab.orig
echo $(blkid /dev/sdb2 | sed 's/.*: //;s/ .*//;s/"//g') / \ \ \ \ ext4 rw,relatime 0 1 > /mnt/etc/fstab.new
echo $(blkid /dev/sdb1 | sed 's/.*: //;s/ .*//;s/"//g') /boot ext4 rw,relatime 0 2 >> /mnt/etc/fstab.new
cat /mnt/etc/fstab.orig >> /mnt/etc/fstab.new
cp /mnt/etc/fstab.new /mnt/etc/fstab</pre>

=== Setup networking ===
<pre>[ ! -d /mnt/etc/network ] mkdir -vp /mnt/etc/networking
cat <<EOF > /mnt/etc/network/interfaces
auto lo
iface lo inet loopback

auto eth0
iface eth0 inet dhcp

EOF</pre>

=== Set the root password ===
When the system boots it will require a root password. This differs from Alpine install media but that's not the objective of this guide. This guide is installing a ready system.

<pre>passwd -R /mnt root</pre>

=== Enable login on UART ===
<pre>sed -i 's/^#ttyS0/ttyS0/' /mnt/etc/inittab</pre>

== Install Alpine from an non-Alpine RISC-V Linux host ==
This section is mainly intended for those trying to install Alpine from one of the vendor images or another RISCV64 install. The apk utility does need to be able to run post-build scripts in order for target installation to function properly.

=== Download a minirootfs to run apk within a chroot ===
<pre>cd /var/tmp
wget https://dl-cdn.alpinelinux.org/edge/releases/riscv64/alpine-minirootfs-20260127-riscv64.tar.gz</pre>
Unzip in /mnt
<pre>cd /mnt
tar xfpz /var/tmp/alpine-minirootfs-20260127-riscv64.tar.gz</pre>
{{Note|
If installing from a non-Alpine host, you may want to install the kernel image and modules first. Come back to this part to chroot and run the apk step and finish up with mkinitfs}}
Chroot into /mnt and run <code>apk add</code>
<pre>chroot /mnt /bin/sh
apk --arch riscv64 --allow-untrusted --initdb add \
alpine-base alpine-baselayout alpine-conf alpine-keys alpine-release alpine-baselayout-data \
kmod openrc dbus util-linux blkid chrony sysfsutils ssl_client openssh ca-certificates-bundle \
alpine-keys ethtool e2fsprogs e2fsprogs-extra libudev-zero libudev-zero-helper parted grep \
busybox-mdev-openrc procps-ng net-tools coreutils doas sed gawk findutils bash shadow pciutils \
mkinitfs</pre>

=== Setup openrc services ===
<pre>for rc in boot/bootmisc boot/hostname boot/modules boot/sysctl boot/urandom boot/networking \
sysinit/devfs sysinit/hwdrivers sysinit/mdev sysinit/modules \
shutdown/mount-ro shutdown/killprocs \
default/dbus default/networking default/chronyd default/local; do
ln -s /etc/init.d/"${rc##*/}" /etc/runlevels/"$rc"
done</pre>

=== Setup fstab within the chroot ===
<pre>cp /etc/fstab /etc/fstab.orig
echo $(blkid /dev/sdb2 | sed 's/.*: //;s/ .*//;s/"//g') / \ \ \ \ ext4 rw,relatime 0 1 > /etc/fstab.new
echo $(blkid /dev/sdb1 | sed 's/.*: //;s/ .*//;s/"//g') /boot ext4 rw,relatime 0 2 >> /etc/fstab.new
cat /etc/fstab.orig >> /etc/fstab.new
cp /etc/fstab.new /etc/fstab</pre>

=== Setup networking ===
<pre>[ ! -d /etc/network ] mkdir -vp /etc/networking
cat <<EOF > /etc/network/interfaces
auto lo
iface lo inet loopback

auto eth0
iface eth0 inet dhcp

EOF</pre>

=== Set the root password ===
When the system boots it will require a root password. This differs from Alpine install media but that's not the objective of this guide. This guide is installing a ready system.

<pre>passwd</pre>

=== Enable login on UART ===
<pre>sed -i 's/^#ttyS0/ttyS0/' /etc/inittab</pre>

== Setting up the boot environment ==
All of the effort up to this point has come down to this. This portion of the guide will assume the kernel being installed is version 6.6.63-ky from the vendor.
=== Install the kernel ===
We created an archive for each method of obtaining a kernel. Now we need to unpack that archive in our buildroot.
<pre>cd /mnt
tar xzf /var/tmp/linux-6.6.63-ky.tgz</pre>
=== Install the esos.elf firmware ===
Copy esos.elf from your very safe place to /mnt/lib/firmware
<pre>doas cp ~/Downloads/esos.elf /mnt/lib/firmware/</pre>
=== Creating the initrd image ===
The methods to obtain a kernel omitted collecting initrd images. Those images would not have been based on Alpine. We'll be using <code>mkinitfs</code> to do this. There are a few modifications we need to make in order for this process to generate an image with all the required bits.
==== Configuring and fixing mkinitfs ====
===== Add esos.elf to mkinitfs/features.d/base.files =====
<pre>echo "/lib/firmware/esos.elf" >> /etc/mkinitfs/features.d/base.files</pre>
===== Add the wireless-regdb database files to base.files =====
{{Note|
You may not need this. If you see a kernel message regarding failure to load regulatory.db with error -2, this will resolve it. Requires install of wireless-regdb apk package.}}
<pre>echo "/lib/firmware/regulatory.*" >> /etc/mkinitfs/features.d/base.files</pre>
===== Add jdb2 to ext4 =====
{{Note|
This may not be necessary. Need to double check it.
The ext4 module depends on the jdb2 module for filesystem journaling. The Alpine kernel does not have ext4 or jbd2 as kernel builtins. If you're using the Alpine provided kernel then you'll need this on the initramfs.
<pre>echo "kernel/fs/jbd2" >> /etc/mkinitfs/features.d/ext4.modules</pre>

===== Prevent mkinitfs from deleting needed firmware =====
The mkinitfs script will delete a directory that shouldn't exist. The files assembled from the features.d includes will have already been staged prior to mkinitfs assembling firmware needed by included modules. We need this not to happen and below is the simplest workaround I could pull together.
Make a copy of mkinitfs
<pre>cp /sbin/mkinitfs /sbin/mkinitfs-rv2</pre>
In the initfs_firmware function of <code>/sbin/mkinitfs-rv2</code> you will find the following lines
<pre> rm -rf "$tmpdir"/lib/firmware
mkdir -p "$tmpdir"/lib/firmware</pre>
Change them to be
<pre> #rm -rf "$tmpdir"/lib/firmware
[ ! -d "$tmpdir"/lib/firmware ] && mkdir -p "$tmpdir"/lib/firmware</pre>

==== Using mkinitfs-rv2 to create an initrd image ====
Installing from an Alpine host
<pre>mkinitfs-rv2 -b /mnt -c /mnt/etc/mkinitfs/mkinitfs.conf -o /mnt/boot/initramfs-6.6.63-ky 6.6.63-ky</pre>

Installing within a chroot
<pre>mkinitfs-rv2 -c /etc/mkinitfs/mkinitfs.conf -o /boot/initramfs-6.6.63-ky 6.6.63-ky</pre>
=== Configure extlinux ===
Create an extlinux.conf file with the following
<pre>default l0
menu title Alpine U-Boot menu
prompt 1
timeout 10

label l0
menu label Alpine Linux 3.24.0_alpha20260127 (Kernel 6.6.63-ky)
linux /vmlinuz-6.6.63-ky
initrd /initramfs-6.6.63-ky
fdt /dtb-6.6.63-ky/ky/x1_orangepi-rv2.dtb
append mtdparts=d420c000.spi-0:64K@0(bootinfo),64K@64K(private),256K@128K(fsbl),64K@384K(env),192K@448K(opensbi),-@640K(uboot) root=UUID=236a5824-0390-42dc-83e3-f02123188f96 console=ttyS0,115200 console=tty1 rootwait rw rootfstype=ext4 earlycon=sbi</pre>

==== A few notes on extlinux.conf ====
* Most device trees are generated in a dtbs/[kernel-version] directory.
* The vendor vmlinuz is a decompressed kernel image, though it shouldn't matter
* The mtdparts kernel parameter isn't absolutely required
* If using a kernel without ext4 and jbd2 modules as builtins, you'll need to append modules=ext4
* Only the right-most console statement seems to get attention. If you're on UART then you'll want <code>console=ttyS0,115200</code> and if you're on the framebuffer you'll want <code>console=tty1</code>.

== Wrapping Up ==

At this point the primary setup is complete. You may want to add some additional packages or configuration but can also be done after booting the RV2 board.

I may have forgotton something(s) which you'll soon discoven. I'll do my best to fold in corrections as I find they're needed or as new information becomes available.

=== Unmount the buildroot ===

<pre>umount /mnt/proc /mnt/sys /mnt/dev /mnt/boot /mnt</pre>

== Usability extras ==

The above should get your OrangePi RV2 booting Alpine Linux. Below are some additional configurations to help make growing your install a little easier. The following assumes you're still chroot /mnt or have booted the system.

=== Add a local user for yourself with escalation privileges ===

Create a user account for yourself with a secondary group of wheel
<pre># Create your account
useradd -G wheel -s /bin/bash -d /home/myuser -m -c "My User" myuser
# Set your password
passwd myuser</pre>

Add a configuration to doas.d for group wheel
<pre>echo permit persist :wheel > /etc/doas.d/00-wheel.conf</pre>

=== Install Avahi for mdns broadcasts ===

Avahi can broadcast names for services provided by your host. The default config in the Alpine package provides a configuration for sshd.

<pre># First setup the hostname
setup-hostname myhost

# Set the hostname
hostname `cat /etc/hostname`

# Install the avahi apk
apk add avahi

# Enable and start the avahi daemon
rc-update add avahi-daemon && rc-service avahi-daemon start</pre>

[[Category:Riscv64]]

Talk:Riscv64 Redo

2026-04-11T02:47:31Z

Aarch0x40: Created blank page

Tutorials and Howtos

2026-04-10T05:45:57Z

Aarch0x40: /* Other Architectures */

[[Image:package_edutainment.svg|right|link=]]
{{TOC left}}

'''Welcome to Tutorials and Howtos, a place of basic and advanced configuration tasks for your Alpine Linux.'''

'''Howtos are smaller articles''' explaining how to perform a particular task with Alpine Linux, that expects a minimal knowledge from reader to perform actions. Howto's have been organized in the below page based on the topics.

'''The [[#Tutorials|tutorials]] are hands-on''' and the reader is expected to try and achieve the goals described in each step, possibly with the help of a good example. The output in one step is the starting point for the following step.

{{Note|
* Contributors are requested to refer to [[Help:Editing]] first and make use of resources like [[How to write a HOWTO]].
* Contributions must be complete articles.
* Don't override already made contributions, unless there is a mistake.
* If you want to request a topic, please add your request in this page's [[Talk:Tutorials_and_Howtos|Discussion]].}}

== Desktop ==

* {{:Daily driver guide}}

=== Networking ===

* [[Bluetooth]] - Instructions for installing and configuring Bluetooth
* [[Bonding]] - Bond (or aggregate) multiple ethernet interfaces
* [[Bridge]] - Configuring a network bridge
** [[Bridge wlan0 to eth0]]
* [[Configure Networking]]
* [[How to configure static routes]]
* Modem
** [[Using HSDPA modem]]
** [[Using serial modem]]
* [[mDNS]] - Howto implement multicast DNS resolution in Alpine.
* [[Multi ISP]] ''(Dual-ISP setup with load-balancing and automatic failover)''
* [[PXE boot]]
* Wi-Fi
** [[Wi-Fi|Connecting to a wireless access point]]
** [[How to setup a wireless access point]] ''(Setting up Secure Wireless AP w/ WPA encryption with bridge to wired network)''
* Use [https://github.com/ifupdown-ng/ifupdown-ng/blob/main/doc/interfaces-vxlan.scd vxlan], if using [[Ifupdown-ng]] instead of [[VLAN]]
* [[Setting up a Home Router]]

=== Backup and data migration ===

* [[Migrating data]]
* [[Rsnapshot]] - setting up periodic backups

=== Other topics ===

* [[Gaming on Alpine]]
* [[Remote Desktop Server]]
* [[Default applications|How to change default application]]
* [[CPU frequency scaling]]
* [[Mimalloc]]
* [[Enable Serial Console on Boot]]
* [[How to build the Alpine Linux kernel]]
* [[Nextcloud]] ''(Self hostable cloud suite - Dropbox Alternative)''
* [[Setting up lm_sensors]]
* [[Fingerprint Authentication with swaylock]]
* [[Mounting a LUKS Encrypted Data Partition at Boot]]
* [[Desktop environments and Window managers|List of supported Desktop environments and Window managers]]

== Diskless ==

* [[Alpine local backup|Alpine local backup (lbu)]] ''(Permanently store your modifications in case your box needs reboot)''
** [[Back Up a Flash Memory Installation]]
** [[Manually editing a existing apkovl]]

== Other Architectures ==

=== APU (PCEngines) ===

* [[Alpine Install: from a disc to PC Engines APU|Alpine on PC Engines APU]]
* [https://github.com/huubsch/Installation-of-Alpine-Linux-on-PC-Engines-APU3/tree/main?tab=readme-ov-file Installation of Alpine Linux on PCEngines APU, legacy BIOS]

=== ARM ===

* [[Alpine on ARM]]

==== Raspberry Pi ====

* [[Raspberry Pi|Raspberry Pi main page]]
* [[Raspberry Pi Bluetooth Speaker|Raspberry Pi - Bluetooth Speaker]]
* [[Linux Router with VPN on a Raspberry Pi|Raspberry Pi - Router with VPN]]
* [[Linux Router with VPN on a Raspberry Pi (IPv6)|Raspberry Pi - Router with VPN (IPv6)]]
* [[Classic install or sys mode on Raspberry Pi|Raspberry Pi - Sys mode install]]
* [[Raspberry Pi LVM on LUKS|Raspberry Pi - Sys mode install - LVM on LUKS]]
* [[RPI Video Receiver|Raspberry Pi - Video Receiver]] ''(network video decoder using Rasperry Pi and omxplayer)''
* [[Raspberry Pi 3 - Browser Client]] - kiosk or digital sign
* [[Raspberry Pi 3 - Configuring it as wireless access point -AP Mode]]
* [[Raspberry Pi 3 - Setting Up Bluetooth]]
* [[Raspberry Pi 4 - Persistent system acting as a NAS and Time Machine]]
* [[Raspberry_Pi_Zero_W_-_Installation|Raspberry Pi Zero W - Installation]]
* [[How to set up Alpine as a wireless router|Raspberry Pi Zero W - Wireless router]] ''(Setting up a firewalled, Wireless AP with wired network on a Pi Zero W)''

=== IBM Z (IBM z Systems) ===

* [[s390x|s390x - Installation]]

=== PowerPC ===

* [[Ppc64le|Powerpc64le - Installation]]

=== RISC-V ===

* [[Riscv64|Running Alpine riscv64 in QEMU]]
* [[Installing Alpine Linux on OrangePi RV2]]

== Security ==

* [[#Desktop security|Desktop security]] lists steps for securing Alpine Linux desktops
* [[Setting up a laptop]] page has detailed guidelines to configure a secured laptop
* [[Securing Alpine Linux|Secure Alpine Linux]] using Security Technical Implementation Guides (STIGs)
* [[Sshguard|SSHGuard]] - Protects hosts against brute-force attacks: monitoring logs, attack detection, blocking using firewall.

== Services ==

{{Note| Services are arranged in alphabetical order.}}

=== Content management systems ===

* [[DokuWiki]] ''(Simple and easy to use wiki, no database required)''
* [[Drupal]] ''(Content Management System (CMS) written in PHP)''
* [[Kopano]] ''(Microsoft Outlook compatible Groupware)''
* [[Mahara]] ''(E-portfolio and social networking system)''
* [[MediaWiki]] ''(Free web-based wiki software application)''
* [[Pastebin]] ''(Pastebin software application)''
* [[WordPress]] ''(Web software to create website or blog)''
* [[Moodle]] ''(Online Learning Management system)''

=== Database ===

* [[MariaDB]] or [[MySQL|MySQL]]

=== DNS ===

* [[DNSCrypt-Proxy]] ''Encrypt and authenticate DNS calls from your system''
* [[Setting up nsd DNS server]]
* [[Small-Time DNS with BIND9]] ''(A simple configuration with ad blocking for your home network)''
* Unbound
** [[Setting up unbound DNS server]]
** [[Using Unbound as an Ad-blocker]] ''(Setup ad blocking for your network)''
* [[TinyDNS Format]]

=== File server ===

* [[Setting up an NFS server|nfs-server]]
* [[Setting up a Samba server|samba-server]] ''(standard file sharing)''
* [[Setting up a samba-ad-dc|samba-ad-dc]] ''(Active Directory compatible domain controller)''

=== Firewall ===

* [https://git.alpinelinux.org/awall/about/ Alpine Wall User's Guide]
** [[Zero-To-Awall]] -''AWall for dummies''
** [[How-To Alpine Wall]] - ''AWall for Shorewall users''
** [[Alpine Wall]] - ''AWall - Firewall management framework - Design Document''
* [[Iptables]]
* [[nftables]]
* [[Uncomplicated Firewall|Uncomplicated Firewall or UFW]]

=== HTTP and web services ===

* [[Althttpd]]
* [[Apache]]
** [[Apache with php-fpm]]
** [[Setting Up Apache with PHP]]
** [[Apache authentication: NTLM Single Signon]]
* [[Darkhttpd]]
* [[Lighttpd]]
** [[Lighttpd Advanced security]]
** [[Setting Up Lighttpd With FastCGI]]
** [[Production Web server: Lighttpd|Production web server: Lighttpd‎‎]]
* [[Nginx]]
** [[Nginx as reverse proxy with acme (letsencrypt)]]
** [[Nginx with PHP]]
* Squid Proxy
** [[Setting up Explicit Squid Proxy]]
** [[Setting up Transparent Squid Proxy]] ''(Covers Squid proxy and URL Filtering system)''
** [[SqStat]] ''(Script to look at active squid users connections)''
* [[Tomcat]]
** [[Production LAMP system: Lighttpd + PHP + MySQL‎‎|Production LAMP system: Lighttpd + PHP + MariaDB/MySQL‎‎]]

=== IRC ===

* [[NgIRCd]] ''(Server for Internet Relay Chat/IRC)''

=== Mail ===

* [[Hosting services on Alpine]] ''(Hosting mail, webservices and other services)''
* [[Hosting Web/Email services on Alpine]]
* Exim/Dovecot
** [[Small-Time Email with Exim and Dovecot]] ''(A simple configuration for your home network.)
** [[Setting up dovecot with imap and tls]]
* [[relay email to gmail (msmtp, mailx, sendmail]]
* [[relay email (nullmailer)]]
* [[Roundcube]] ''(Webmail system)''
* [[Setting up postfix with virtual domains]]
* Server protection
** [[Setting up clamsmtp]]

=== Monitoring ===

* [[Awstats]] ''(Free log file analyzer)''
* [[Cacti: traffic analysis and monitoring network]] ''(Front-end for rrdtool networking monitor)''
* [[Cvechecker]] ''(Compare installed packages for Common Vulnerabilities Exposure)'' 
* [[Linfo]]
* [[Obtaining user information via SNMP]] ''(Using squark-auth-snmp as a Squid authentication helper)'' 
* [[PhpSysInfo]] ''(A simple application that displays information about the host it's running on)''
* [[Logcheck]] ''(log file monitoring tool)''
* [[Matomo]] ''(A real time web analytics software program)''
* [[Rasdaemon]] ''(Platform Reliability, Availability and Serviceability monitoring tool)''
* [[Setting up A Network Monitoring and Inventory System]] ''(Nagios + OpenAudit and related components)'' 
** [[Setting up NRPE daemon]] ''(Performs remote Nagios checks)'' 
* [[Setting Up Fprobe And Ntop|Ntop]] ''(NetFlow collection and analysis using a remote fprobe instance; for alpine 3.10-3.12 only)'' 
* [[SqStat]] ''(Script to look at active squid users connections)''
* [[Traffic monitoring]] 
** [[Setting up monitoring using rrdtool (and rrdcollect)]]
** [[Setting up traffic monitoring using rrdtool (and snmp)]] 
* [[Zabbix|Zabbix - the professional complete manager]] ''(Monitor and track the status of network services and hardware)''
* [[ZoneMinder video camera security and surveillance]]

=== Remote Administration ===

* ACF
** [[Changing passwords for ACF|ACF - changing passwords]]
** [[Generating SSL certs with ACF]] 
** [[setup-acf| ACF - setup]] ''(Configures ACF (webconfiguration/webmin) so you can manage your box through https)''
* [[Setting up a SSH server]] ''(Using ssh is a good way to administer your box remotely)''
** [[HOWTO OpenSSH 2FA with password and Google Authenticator |OpenSSH 2FA]] ''(A simple two factor setup for OpenSSH)''
* [[OpenVCP]] ''(VServer Control Panel)''
* [[PhpMyAdmin]] ''(Web-based administration tool for MYSQL)''
* [[PhpPgAdmin]] ''(Web-based administration tool for PostgreSQL)''
* [[Webmin]] ''(A web-based interface for Linux system)''

=== Telephony ===

* [[FreePBX|FreePBX on Alpine Linux]]
* [[Setting up Zaptel/Asterisk on Alpine]]
* [[Kamailio]] ''(SIP Server, formerly OpenSER)''

=== VPN ===
* [[Freeradius Active Directory Integration]]
* [[GNUnet]]
* [[IGMPproxy]]
* [[Setting up a OpenVPN server|OpenVPN server]] ''(Allowing single users or devices to remotely connect to your network)''
* [[OpenVSwitch]]
* [[Openconnect-SSO in Docker]]
* [[Tor]]
* [[Using Alpine on Windows domain with IPSEC isolation]]
* [[Configure a Wireguard interface (wg)|Wireguard]]
* [[Vpnc]]

=== Other Servers ===

* [[apcupsd]] ''(UPS Monitoring with apcupsd)''
* [[Chrony and GPSD | Chrony, gpsd, and a garmin LVC 18 as a Stratum 1 NTP source ]]
* [[Glpi]] ''(Manage inventory of technical resources)''
* [[How to setup a Alpine Linux mirror]]
* [[nut-ups|NUT UPS]] ''(UPS Monitoring with Network UPS Tools)''
* [[Odoo]]
* [[Configure OpenLDAP | OpenLDAP]] ''(Installing and configuring the Alpine package for OpenLDAP)''
* [[Setting up a LLDAP server|lldap-server]] ''(Directory Server)''
* [[Setting up Transmission (bittorrent) with Clutch WebUI]]

== Software development ==

* [[Cgit]]
* [[OsTicket]] ''(Ticket system)''
* [[Patchwork]] ''(Patch review management system)''
* [[Redmine]] ''(Project management system) [Deprecated]''
* [[Request Tracker]] ''(Ticket system)''
* [[Setting up trac wiki|Trac]] ''(Enhanced wiki and issue tracking system for software development projects)''
* [[Ansible]] ''(Configuration management)''
* [[Installing Oracle Java|Oracle Java (installation)]]

== Storage ==

* [[Setting up disks manually|Manual partitioning]]
* [[Disk Replication with DRBD|DRBD: Disk Replication]]
* [[Filesystems]]
** [[Burning ISOs]]
* [[Setting up iSCSI|iSCSI Setup]]
** [[iSCSI Raid and Clustered File Systems]]
** [[Linux iSCSI Target (TCM)|iSCSI Target (TCM)/LinuxIO (LIO)]]
** [[Linux iSCSI Target (tgt)|User space iSCSI Target (tgt)]]
* [[Setting up Logical Volumes with LVM|LVM Setup]]
** [[Setting up LVM on GPT-labeled disks|LVM on GPT-labeled disks]]
** [[Installing on GPT LVM|LVM on GPT-labeled disks (updated)]]
** [[LVM on LUKS]]
* RAID
** [[Raid Administration]]
** [[Setting up a software RAID array]]
* [[ZFS]]
** [[Root on ZFS with native encryption]]
** [[Setting up ZFS on LUKS]]
* [[CEPH|CEPH]]

== Virtualization ==

* [[Docker]]
* [[Installing Alpine in a virtual machine]]
** [[Install Alpine on VMware ESXi]]
* [[KVM]] ''(Setting up Alpine as a KVM hypervisor)''
* [[LXC]] ''(Setting up a Linux container in Alpine Linux)''
* [[QEMU]]
* Xen
** [[Xen Dom0]] ''(Setting up Alpine as a dom0 for Xen hypervisor)''
** [[Xen Dom0 on USB or SD]]
** [[Create Alpine Linux PV DomU|Xen DomU (paravirtualized)]]
** [[Xen LiveCD]]
** [[Xen PCI Passthrough]]
** [[K8s]] Building a K8s Kubernetes Cluster on Alpine Linux
* [[Runc]]

== [[Simple_Walkthrough]] ==
* [[About-virtualization-simple]]
* [[LXC_Alpinelinux_Simple]]
* [[Qemu-simple]]

== Tutorials ==

* [[TTY_Autologin|TTY Autologin]]
* [[Kexec|Faster rebooting with kexec]]
* [[Dynamic Multipoint VPN (DMVPN)]] combined with [[Small Office Services]]
* [[DIY Fully working Alpine Linux for Allwinner and Other ARM SOCs]]
* [[Fault Tolerant Routing with Alpine Linux]]
* [[High Availability High Performance Web Cache]] ''(uCarp + HAProxy for High Availability Services such as Squid web proxy)''
* [[Linux iSCSI Target (TCM)]]
* [[ISP Mail Server 3.x HowTo]] ''(Postfix+PostfixAdmin+DoveCot+Roundcube+ClamAV+Spamd - A full-service ISP mail server)''
* [[Grommunio Mail Server]] ''(Mariadb+Postfix+Rspamd+Grommunio - Full-service mail server as MS exchange replacement)''
* [[Replacing non-Alpine Linux with Alpine remotely]]
* [[Streaming Security Camera Video with VLC]]
* [[Install Alpine on a btrfs filesystem with refind as boot manager]]
* [[Compile software from source|How to Compile a software from source in Alpine Linux]]
* [https://ww2.coastal.edu/mmurphy2/oer/alpine/ Alpine Linux tutorials - Dr Murphy, Computing Science Associate Professor]
* [[Michael's base installation procedure|Michael's base installation procedure]]
* [[Michael's cwm desktop (minimal)|Michael's cwm desktop (minimal)]]
* [[Michael's sway desktop (minimal)|Michael's Sway desktop (minimal)]]
* [[Sway_customization_guide|Sway customization guide]] ''(Tutorial re Sway config file basics)''
* [[Using Distrobox For VR Gaming|Using Distrobox For VR Gaming]]

Tutorials and Howtos

2026-04-10T05:45:17Z

Aarch0x40: /* Other Architectures */

[[Image:package_edutainment.svg|right|link=]]
{{TOC left}}

'''Welcome to Tutorials and Howtos, a place of basic and advanced configuration tasks for your Alpine Linux.'''

'''Howtos are smaller articles''' explaining how to perform a particular task with Alpine Linux, that expects a minimal knowledge from reader to perform actions. Howto's have been organized in the below page based on the topics.

'''The [[#Tutorials|tutorials]] are hands-on''' and the reader is expected to try and achieve the goals described in each step, possibly with the help of a good example. The output in one step is the starting point for the following step.

{{Note|
* Contributors are requested to refer to [[Help:Editing]] first and make use of resources like [[How to write a HOWTO]].
* Contributions must be complete articles.
* Don't override already made contributions, unless there is a mistake.
* If you want to request a topic, please add your request in this page's [[Talk:Tutorials_and_Howtos|Discussion]].}}

== Desktop ==

* {{:Daily driver guide}}

=== Networking ===

* [[Bluetooth]] - Instructions for installing and configuring Bluetooth
* [[Bonding]] - Bond (or aggregate) multiple ethernet interfaces
* [[Bridge]] - Configuring a network bridge
** [[Bridge wlan0 to eth0]]
* [[Configure Networking]]
* [[How to configure static routes]]
* Modem
** [[Using HSDPA modem]]
** [[Using serial modem]]
* [[mDNS]] - Howto implement multicast DNS resolution in Alpine.
* [[Multi ISP]] ''(Dual-ISP setup with load-balancing and automatic failover)''
* [[PXE boot]]
* Wi-Fi
** [[Wi-Fi|Connecting to a wireless access point]]
** [[How to setup a wireless access point]] ''(Setting up Secure Wireless AP w/ WPA encryption with bridge to wired network)''
* Use [https://github.com/ifupdown-ng/ifupdown-ng/blob/main/doc/interfaces-vxlan.scd vxlan], if using [[Ifupdown-ng]] instead of [[VLAN]]
* [[Setting up a Home Router]]

=== Backup and data migration ===

* [[Migrating data]]
* [[Rsnapshot]] - setting up periodic backups

=== Other topics ===

* [[Gaming on Alpine]]
* [[Remote Desktop Server]]
* [[Default applications|How to change default application]]
* [[CPU frequency scaling]]
* [[Mimalloc]]
* [[Enable Serial Console on Boot]]
* [[How to build the Alpine Linux kernel]]
* [[Nextcloud]] ''(Self hostable cloud suite - Dropbox Alternative)''
* [[Setting up lm_sensors]]
* [[Fingerprint Authentication with swaylock]]
* [[Mounting a LUKS Encrypted Data Partition at Boot]]
* [[Desktop environments and Window managers|List of supported Desktop environments and Window managers]]

== Diskless ==

* [[Alpine local backup|Alpine local backup (lbu)]] ''(Permanently store your modifications in case your box needs reboot)''
** [[Back Up a Flash Memory Installation]]
** [[Manually editing a existing apkovl]]

== Other Architectures ==

=== APU (PCEngines) ===

* [[Alpine Install: from a disc to PC Engines APU|Alpine on PC Engines APU]]
* [https://github.com/huubsch/Installation-of-Alpine-Linux-on-PC-Engines-APU3/tree/main?tab=readme-ov-file Installation of Alpine Linux on PCEngines APU, legacy BIOS]

=== ARM ===

* [[Alpine on ARM]]

==== Raspberry Pi ====

* [[Raspberry Pi|Raspberry Pi main page]]
* [[Raspberry Pi Bluetooth Speaker|Raspberry Pi - Bluetooth Speaker]]
* [[Linux Router with VPN on a Raspberry Pi|Raspberry Pi - Router with VPN]]
* [[Linux Router with VPN on a Raspberry Pi (IPv6)|Raspberry Pi - Router with VPN (IPv6)]]
* [[Classic install or sys mode on Raspberry Pi|Raspberry Pi - Sys mode install]]
* [[Raspberry Pi LVM on LUKS|Raspberry Pi - Sys mode install - LVM on LUKS]]
* [[RPI Video Receiver|Raspberry Pi - Video Receiver]] ''(network video decoder using Rasperry Pi and omxplayer)''
* [[Raspberry Pi 3 - Browser Client]] - kiosk or digital sign
* [[Raspberry Pi 3 - Configuring it as wireless access point -AP Mode]]
* [[Raspberry Pi 3 - Setting Up Bluetooth]]
* [[Raspberry Pi 4 - Persistent system acting as a NAS and Time Machine]]
* [[Raspberry_Pi_Zero_W_-_Installation|Raspberry Pi Zero W - Installation]]
* [[How to set up Alpine as a wireless router|Raspberry Pi Zero W - Wireless router]] ''(Setting up a firewalled, Wireless AP with wired network on a Pi Zero W)''

=== IBM Z (IBM z Systems) ===

* [[s390x|s390x - Installation]]

=== RISC-V ===

* [[Riscv64|Running Alpine riscv64 in QEMU]]
* [[Installing Alpine Linux on OrangePi RV2]]

=== PowerPC ===

* [[Ppc64le|Powerpc64le - Installation]]

== Security ==

* [[#Desktop security|Desktop security]] lists steps for securing Alpine Linux desktops
* [[Setting up a laptop]] page has detailed guidelines to configure a secured laptop
* [[Securing Alpine Linux|Secure Alpine Linux]] using Security Technical Implementation Guides (STIGs)
* [[Sshguard|SSHGuard]] - Protects hosts against brute-force attacks: monitoring logs, attack detection, blocking using firewall.

== Services ==

{{Note| Services are arranged in alphabetical order.}}

=== Content management systems ===

* [[DokuWiki]] ''(Simple and easy to use wiki, no database required)''
* [[Drupal]] ''(Content Management System (CMS) written in PHP)''
* [[Kopano]] ''(Microsoft Outlook compatible Groupware)''
* [[Mahara]] ''(E-portfolio and social networking system)''
* [[MediaWiki]] ''(Free web-based wiki software application)''
* [[Pastebin]] ''(Pastebin software application)''
* [[WordPress]] ''(Web software to create website or blog)''
* [[Moodle]] ''(Online Learning Management system)''

=== Database ===

* [[MariaDB]] or [[MySQL|MySQL]]

=== DNS ===

* [[DNSCrypt-Proxy]] ''Encrypt and authenticate DNS calls from your system''
* [[Setting up nsd DNS server]]
* [[Small-Time DNS with BIND9]] ''(A simple configuration with ad blocking for your home network)''
* Unbound
** [[Setting up unbound DNS server]]
** [[Using Unbound as an Ad-blocker]] ''(Setup ad blocking for your network)''
* [[TinyDNS Format]]

=== File server ===

* [[Setting up an NFS server|nfs-server]]
* [[Setting up a Samba server|samba-server]] ''(standard file sharing)''
* [[Setting up a samba-ad-dc|samba-ad-dc]] ''(Active Directory compatible domain controller)''

=== Firewall ===

* [https://git.alpinelinux.org/awall/about/ Alpine Wall User's Guide]
** [[Zero-To-Awall]] -''AWall for dummies''
** [[How-To Alpine Wall]] - ''AWall for Shorewall users''
** [[Alpine Wall]] - ''AWall - Firewall management framework - Design Document''
* [[Iptables]]
* [[nftables]]
* [[Uncomplicated Firewall|Uncomplicated Firewall or UFW]]

=== HTTP and web services ===

* [[Althttpd]]
* [[Apache]]
** [[Apache with php-fpm]]
** [[Setting Up Apache with PHP]]
** [[Apache authentication: NTLM Single Signon]]
* [[Darkhttpd]]
* [[Lighttpd]]
** [[Lighttpd Advanced security]]
** [[Setting Up Lighttpd With FastCGI]]
** [[Production Web server: Lighttpd|Production web server: Lighttpd‎‎]]
* [[Nginx]]
** [[Nginx as reverse proxy with acme (letsencrypt)]]
** [[Nginx with PHP]]
* Squid Proxy
** [[Setting up Explicit Squid Proxy]]
** [[Setting up Transparent Squid Proxy]] ''(Covers Squid proxy and URL Filtering system)''
** [[SqStat]] ''(Script to look at active squid users connections)''
* [[Tomcat]]
** [[Production LAMP system: Lighttpd + PHP + MySQL‎‎|Production LAMP system: Lighttpd + PHP + MariaDB/MySQL‎‎]]

=== IRC ===

* [[NgIRCd]] ''(Server for Internet Relay Chat/IRC)''

=== Mail ===

* [[Hosting services on Alpine]] ''(Hosting mail, webservices and other services)''
* [[Hosting Web/Email services on Alpine]]
* Exim/Dovecot
** [[Small-Time Email with Exim and Dovecot]] ''(A simple configuration for your home network.)
** [[Setting up dovecot with imap and tls]]
* [[relay email to gmail (msmtp, mailx, sendmail]]
* [[relay email (nullmailer)]]
* [[Roundcube]] ''(Webmail system)''
* [[Setting up postfix with virtual domains]]
* Server protection
** [[Setting up clamsmtp]]

=== Monitoring ===

* [[Awstats]] ''(Free log file analyzer)''
* [[Cacti: traffic analysis and monitoring network]] ''(Front-end for rrdtool networking monitor)''
* [[Cvechecker]] ''(Compare installed packages for Common Vulnerabilities Exposure)'' 
* [[Linfo]]
* [[Obtaining user information via SNMP]] ''(Using squark-auth-snmp as a Squid authentication helper)'' 
* [[PhpSysInfo]] ''(A simple application that displays information about the host it's running on)''
* [[Logcheck]] ''(log file monitoring tool)''
* [[Matomo]] ''(A real time web analytics software program)''
* [[Rasdaemon]] ''(Platform Reliability, Availability and Serviceability monitoring tool)''
* [[Setting up A Network Monitoring and Inventory System]] ''(Nagios + OpenAudit and related components)'' 
** [[Setting up NRPE daemon]] ''(Performs remote Nagios checks)'' 
* [[Setting Up Fprobe And Ntop|Ntop]] ''(NetFlow collection and analysis using a remote fprobe instance; for alpine 3.10-3.12 only)'' 
* [[SqStat]] ''(Script to look at active squid users connections)''
* [[Traffic monitoring]] 
** [[Setting up monitoring using rrdtool (and rrdcollect)]]
** [[Setting up traffic monitoring using rrdtool (and snmp)]] 
* [[Zabbix|Zabbix - the professional complete manager]] ''(Monitor and track the status of network services and hardware)''
* [[ZoneMinder video camera security and surveillance]]

=== Remote Administration ===

* ACF
** [[Changing passwords for ACF|ACF - changing passwords]]
** [[Generating SSL certs with ACF]] 
** [[setup-acf| ACF - setup]] ''(Configures ACF (webconfiguration/webmin) so you can manage your box through https)''
* [[Setting up a SSH server]] ''(Using ssh is a good way to administer your box remotely)''
** [[HOWTO OpenSSH 2FA with password and Google Authenticator |OpenSSH 2FA]] ''(A simple two factor setup for OpenSSH)''
* [[OpenVCP]] ''(VServer Control Panel)''
* [[PhpMyAdmin]] ''(Web-based administration tool for MYSQL)''
* [[PhpPgAdmin]] ''(Web-based administration tool for PostgreSQL)''
* [[Webmin]] ''(A web-based interface for Linux system)''

=== Telephony ===

* [[FreePBX|FreePBX on Alpine Linux]]
* [[Setting up Zaptel/Asterisk on Alpine]]
* [[Kamailio]] ''(SIP Server, formerly OpenSER)''

=== VPN ===
* [[Freeradius Active Directory Integration]]
* [[GNUnet]]
* [[IGMPproxy]]
* [[Setting up a OpenVPN server|OpenVPN server]] ''(Allowing single users or devices to remotely connect to your network)''
* [[OpenVSwitch]]
* [[Openconnect-SSO in Docker]]
* [[Tor]]
* [[Using Alpine on Windows domain with IPSEC isolation]]
* [[Configure a Wireguard interface (wg)|Wireguard]]
* [[Vpnc]]

=== Other Servers ===

* [[apcupsd]] ''(UPS Monitoring with apcupsd)''
* [[Chrony and GPSD | Chrony, gpsd, and a garmin LVC 18 as a Stratum 1 NTP source ]]
* [[Glpi]] ''(Manage inventory of technical resources)''
* [[How to setup a Alpine Linux mirror]]
* [[nut-ups|NUT UPS]] ''(UPS Monitoring with Network UPS Tools)''
* [[Odoo]]
* [[Configure OpenLDAP | OpenLDAP]] ''(Installing and configuring the Alpine package for OpenLDAP)''
* [[Setting up a LLDAP server|lldap-server]] ''(Directory Server)''
* [[Setting up Transmission (bittorrent) with Clutch WebUI]]

== Software development ==

* [[Cgit]]
* [[OsTicket]] ''(Ticket system)''
* [[Patchwork]] ''(Patch review management system)''
* [[Redmine]] ''(Project management system) [Deprecated]''
* [[Request Tracker]] ''(Ticket system)''
* [[Setting up trac wiki|Trac]] ''(Enhanced wiki and issue tracking system for software development projects)''
* [[Ansible]] ''(Configuration management)''
* [[Installing Oracle Java|Oracle Java (installation)]]

== Storage ==

* [[Setting up disks manually|Manual partitioning]]
* [[Disk Replication with DRBD|DRBD: Disk Replication]]
* [[Filesystems]]
** [[Burning ISOs]]
* [[Setting up iSCSI|iSCSI Setup]]
** [[iSCSI Raid and Clustered File Systems]]
** [[Linux iSCSI Target (TCM)|iSCSI Target (TCM)/LinuxIO (LIO)]]
** [[Linux iSCSI Target (tgt)|User space iSCSI Target (tgt)]]
* [[Setting up Logical Volumes with LVM|LVM Setup]]
** [[Setting up LVM on GPT-labeled disks|LVM on GPT-labeled disks]]
** [[Installing on GPT LVM|LVM on GPT-labeled disks (updated)]]
** [[LVM on LUKS]]
* RAID
** [[Raid Administration]]
** [[Setting up a software RAID array]]
* [[ZFS]]
** [[Root on ZFS with native encryption]]
** [[Setting up ZFS on LUKS]]
* [[CEPH|CEPH]]

== Virtualization ==

* [[Docker]]
* [[Installing Alpine in a virtual machine]]
** [[Install Alpine on VMware ESXi]]
* [[KVM]] ''(Setting up Alpine as a KVM hypervisor)''
* [[LXC]] ''(Setting up a Linux container in Alpine Linux)''
* [[QEMU]]
* Xen
** [[Xen Dom0]] ''(Setting up Alpine as a dom0 for Xen hypervisor)''
** [[Xen Dom0 on USB or SD]]
** [[Create Alpine Linux PV DomU|Xen DomU (paravirtualized)]]
** [[Xen LiveCD]]
** [[Xen PCI Passthrough]]
** [[K8s]] Building a K8s Kubernetes Cluster on Alpine Linux
* [[Runc]]

== [[Simple_Walkthrough]] ==
* [[About-virtualization-simple]]
* [[LXC_Alpinelinux_Simple]]
* [[Qemu-simple]]

== Tutorials ==

* [[TTY_Autologin|TTY Autologin]]
* [[Kexec|Faster rebooting with kexec]]
* [[Dynamic Multipoint VPN (DMVPN)]] combined with [[Small Office Services]]
* [[DIY Fully working Alpine Linux for Allwinner and Other ARM SOCs]]
* [[Fault Tolerant Routing with Alpine Linux]]
* [[High Availability High Performance Web Cache]] ''(uCarp + HAProxy for High Availability Services such as Squid web proxy)''
* [[Linux iSCSI Target (TCM)]]
* [[ISP Mail Server 3.x HowTo]] ''(Postfix+PostfixAdmin+DoveCot+Roundcube+ClamAV+Spamd - A full-service ISP mail server)''
* [[Grommunio Mail Server]] ''(Mariadb+Postfix+Rspamd+Grommunio - Full-service mail server as MS exchange replacement)''
* [[Replacing non-Alpine Linux with Alpine remotely]]
* [[Streaming Security Camera Video with VLC]]
* [[Install Alpine on a btrfs filesystem with refind as boot manager]]
* [[Compile software from source|How to Compile a software from source in Alpine Linux]]
* [https://ww2.coastal.edu/mmurphy2/oer/alpine/ Alpine Linux tutorials - Dr Murphy, Computing Science Associate Professor]
* [[Michael's base installation procedure|Michael's base installation procedure]]
* [[Michael's cwm desktop (minimal)|Michael's cwm desktop (minimal)]]
* [[Michael's sway desktop (minimal)|Michael's Sway desktop (minimal)]]
* [[Sway_customization_guide|Sway customization guide]] ''(Tutorial re Sway config file basics)''
* [[Using Distrobox For VR Gaming|Using Distrobox For VR Gaming]]

Talk:Installing Alpine Linux on OrangePi RV2

2026-04-10T05:39:35Z

Aarch0x40: Created blank page

Installing Alpine Linux on OrangePi RV2

2026-04-10T05:39:20Z

Aarch0x40:

{{Draft}}
[[Main Page]] > [[:Category:Architectures|Architectures]] > [[Riscv64]] > Installing Alpine Linux on OrangePi RV2
 
{{Warning|The contributors to the Alpine Linux project are not responsible for any damage/loss experienced by using the following guide. This article is provided as a general reference. It is assumed that the implementer will have the knowledge and ability to close the gap between what is described here and their specific setup.}}

The [http://www.orangepi.org/html/hardWare/computerAndMicrocontrollers/details/Orange-Pi-RV2.html OrangePi RV2] is a credit-card sized development board with a Ky X1 8-Core SoC. The Ky X1 is for all intents and purposes a SpacemiT K1 SoC. The remainder of this guide is more likely to use the terms SpacemiT or K1 as is prevalent throughout the Linux community. Please understand that these terms all refer to the same RISC-V ISA implementation.

This guide assumes that the manufacturer provided [https://github.com/riscv-software-src/opensbi OpenSBI] and [https://u-boot.org/ U-Boot] binaries have been applied to the SPI Flash device. This stock bootloader will look for an <code>extlinux/extlinux.conf</code> which will be used to configure the boot process.

Those following this guide may find it useful to have a USB UART serial cable available to debug kernel loading.

This guide borrows heavily from the article [https://arvanta.net/alpine/install-alpine-riscv64-qemu-uboot/ install Alpine Linux riscv64 under qemu with u-boot loader] by Milan P. Stanić and posted to [[Riscv64]] by [[User:AnIDFB]].

== Known issues ==
 
{{Warning|The following are the issues that are known to exist between the result of this guide and the manufacturer provided image}}

* Wireless (Wi-Fi & Bluetooth) is not functional
* Some kernel sources have an issue with starting the framebuffer
* Manufacturer tools are not included

This guide was assembled as a dumping of my personal notes. It's being updated as I come across new information. Alpine does run on the RV2 albeit not directly out of the box. Will do my best to reference external materials so that this article may provide some insight to others while still under development. The above may not be the only issues but hopefully there's enough information here to get you going.

== Kernel and Firmware ==
There are a few different options for kernels. The extent of coverage documented here is largely due to my initial ignorance. I have found a few sources for mostly workable kernels. None of them works 100%. SpacemiT is still in the process upstreaming functionality.

=== Obtaining the ESOS firmware ===
The processor being used on the RV2 requires a firmware to function properly. This file is available from the vendor images, in third party distributions and in the [https://github.com/orangepi-xunlong/orangepi-build orangepi-xunlong/orangepi-build] GitHub repository. The subdirectory containing the required file is [https://github.com/orangepi-xunlong/orangepi-build/tree/next/external/packages/bsp/ky/usr/lib/firmware external/packages/bsp/ky/usr/lib/firmware]. Download the file <code>esos.elf</code>. Keep the download in a safe place and also <code>/lib/firmware</code>. The <code>/lib/firmware</code> directory is also where you'll find this file within the vendor's image or an initrd image.
{{Note|
Changes to mkinitfs will be needed in order for this firmware to be included. More information on that will be provided further down the document}}
=== Obtaining the Vendor kernel ===
Open a browser to the [http://www.orangepi.org/html/hardWare/computerAndMicrocontrollers/service-and-support/Orange-Pi-RV2.html OrangePI RV2 Download] page.

Click on the "Downloads" button for the Ubuntu Image. This will take you to a Google Drive folder. Download the Orangepirv2_1.0.0_ubuntu_noble_server_linux6.6.63.7z.

Decompress this file after downloading using your favorite archive utility. It will expand to a directory containing Orangepirv2_1.0.0_ubuntu_noble_server_linux6.6.63.img and shasum file.

Attach the image to a loop device and mount the root partition.
<pre># Find the first available loop device
doas losetup --find

# Assuming the first found available device is /dev/loop0
doas losetup -P /dev/loop0 Orangepirv2_1.0.0_ubuntu_noble_server_linux6.6.63.img

# Mount the root slice
doas mount /dev/loop0p1 /mnt
</pre>

Archive the vendor kernel
<pre>cd /mnt
tar czf /var/tmp/linux-6.6.63-ky.tgz boot/vmlinuz-6.6.63-ky boot/System.map-6.6.63-ky boot/config-6.6.63-ky boot/dtb-6.6.63-ky lib/modules/6.6.63-ky</pre>
{{Note|
You probably want to put the resulting archive in a safer place than /var/tmp at this point. There's a bit to do before we'll need it.}}

Unmount and detach the vendor image
<pre>cd -
doas umount /mnt
doas losetup -d /dev/loop0</pre>
=== Will Alpine's kernel work? (TBD) ===
{{Note|
Need to revisit this}}
=== Building from source ===
There have been 2 main repositories for patched kernel sources.

* [https://github.com/jasonmontleon/linux-spacemit jasonmontleon/linux-spacemit]
* [https://github.com/BredOS/linux-bredos BredOS/linux-bredos]

The linux-spacemit repository is used by RedHat employee Jason Montleon in building out their RISCV64 support. The linux-bredos repository is used by the BredOS project which supports the RV2 and has provides downloadable images for the board. There is cross contribution between these two repositories. A lot of what I've learned to assemble this guide is attributed to these projects.

==== Setting up a workspace ====

Begin by setting up a RISC-V workspace by following [[Riscv64|Running Alpine riscv64 in QEMU]]. You'll need to establish a build environment in this QEMU guest.

<pre>doas apk add alpine-sdk bison flex openssl-dev ncurses ncurses-dev</pre>

{{Note|
<code>ncurses</code> and <code>ncurses-dev</code> aren't a hard requirements but are useful if you want to run <code>make menuconfig</code>}}

==== Cloning the source, configuring and building the kernel ====

{{Note|
This is needs a redo.}}

== Preparing the media ==

=== Partition and setup the filesystems ===
==== Install parted package ====
<pre>doas apk add parted</pre>
==== Insert, partition and format the boot media ====

The media can be either an SD card or USB drive. An 2280 PCIe NVMe is also possibly if you have the ability to write it from the host setting up the media. For the purposes of this guide we will refer to our boot media as <code>/dev/sdb</code>. The following section requires a root shell.

<pre>alias p="parted -sa optimal /dev/sdb"
p mklabel gpt
p mkpart boot ext4 0G 512M
p set 1 boot
p mkpart root ext4 512M 100%
p p</pre>

The final command should produce output to confirm the result of the executed commands. It should look something like the following.

<pre>Model: Generic STORAGE DEVICE (scsi)
Disk /dev/sdb: 15.5GB
Sector size (logical/physical): 512B/512B
Partition Table: gpt
Disk Flags:

Number Start End Size File system Name Flags
1 1049kB 512MB 511MB ext4 boot boot, esp
2 512MB 15.5GB 15.0GB root
</pre>

If all looks good, then we can proceed with formatting the partitions

<pre>mkfs.ext4 /dev/sdb1 && mkfs.ext4 /dev/sdb2</pre>

Mount the filesystems and lay some preliminary groundwork.

<pre># Mount the target root slice
mount /dev/sdb2 /mnt

# Create mount point for boot slice
[ ! -d /mnt/boot ] && mkdir -vp /mnt/boot

# Mount boot slice
mount /dev/sdb1 /mnt/boot

# Create directory for extlinux config
[ ! -d /mnt/boot/extlinux ] && mkdir -vp /mnt/boot/extlinux

# Create directory for apk config
[ ! -d /mnt/etc/apk ] && mkdir -vp /mnt/etc/apk

# Create mount point for devfs
[ ! -d /mnt/dev ] && mkdir -vp /mnt/dev

# Create mount point for procfs
[ ! -d /mnt/proc ] && mkdir -vp /mnt/proc

# Create mount point for sysfs
[ ! -d /mnt/sys ] && mkdir -vp /mnt/sys

# Use bind mounts for dev proc and sys within the target device
mount -o bind /dev /mnt/dev && mount -o bind /proc /mnt/proc && mount -o bind /sys /mnt/sys

# Configure apk package manager
cat <<EOF > /mnt/etc/apk/repositories
#/media/vda1/apks
http://dl-cdn.alpinelinux.org/alpine/edge/main
http://dl-cdn.alpinelinux.org/alpine/edge/community
http://dl-cdn.alpinelinux.org/alpine/edge/testing
EOF
</pre>
== Install Alpine from an Alpine host ==

=== Install Alpine with apk ===
Some of what is going to be installed is up to your choosing. This should be enough to get you going and demonstrate how to target an apk installation.
<pre>apk --root /mnt --arch riscv64 --allow-untrusted --initdb add \
alpine-base alpine-baselayout alpine-conf alpine-keys alpine-release alpine-baselayout-data \
kmod openrc dbus util-linux blkid chrony sysfsutils ssl_client openssh ca-certificates-bundle \
alpine-keys ethtool e2fsprogs e2fsprogs-extra libudev-zero libudev-zero-helper parted grep \
busybox-mdev-openrc procps-ng net-tools coreutils doas sed gawk findutils bash shadow pciutils \
mkinitfs</pre>

=== Setup openrc services ===
<pre>for rc in boot/bootmisc boot/hostname boot/modules boot/sysctl boot/urandom boot/networking \
sysinit/devfs sysinit/hwdrivers sysinit/mdev sysinit/modules \
shutdown/mount-ro shutdown/killprocs \
default/dbus default/networking default/chronyd default/local; do
ln -s /etc/init.d/"${rc##*/}" /mnt/etc/runlevels/"$rc"
done</pre>

=== Setup fstab ===
<pre>cp /mnt/etc/fstab /mnt/etc/fstab.orig
echo $(blkid /dev/sdb2 | sed 's/.*: //;s/ .*//;s/"//g') / \ \ \ \ ext4 rw,relatime 0 1 > /mnt/etc/fstab.new
echo $(blkid /dev/sdb1 | sed 's/.*: //;s/ .*//;s/"//g') /boot ext4 rw,relatime 0 2 >> /mnt/etc/fstab.new
cat /mnt/etc/fstab.orig >> /mnt/etc/fstab.new
cp /mnt/etc/fstab.new /mnt/etc/fstab</pre>

=== Setup networking ===
<pre>[ ! -d /mnt/etc/network ] mkdir -vp /mnt/etc/networking
cat <<EOF > /mnt/etc/network/interfaces
auto lo
iface lo inet loopback

auto eth0
iface eth0 inet dhcp

EOF</pre>

=== Set the root password ===
When the system boots it will require a root password. This differs from Alpine install media but that's not the objective of this guide. This guide is installing a ready system.

<pre>passwd -R /mnt root</pre>

=== Enable login on UART ===
<pre>sed -i 's/^#ttyS0/ttyS0/' /mnt/etc/inittab</pre>

== Install Alpine from an non-Alpine RISC-V Linux host ==
This section is mainly intended for those trying to install Alpine from one of the vendor images or another RISCV64 install. The apk utility does need to be able to run post-build scripts in order for target installation to function properly.

=== Download a minirootfs to run apk within a chroot ===
<pre>cd /var/tmp
wget https://dl-cdn.alpinelinux.org/edge/releases/riscv64/alpine-minirootfs-20260127-riscv64.tar.gz</pre>
Unzip in /mnt
<pre>cd /mnt
tar xfpz /var/tmp/alpine-minirootfs-20260127-riscv64.tar.gz</pre>
{{Note|
If installing from a non-Alpine host, you may want to install the kernel image and modules first. Come back to this part to chroot and run the apk step and finish up with mkinitfs}}
Chroot into /mnt and run <code>apk add</code>
<pre>chroot /mnt /bin/sh
apk --arch riscv64 --allow-untrusted --initdb add \
alpine-base alpine-baselayout alpine-conf alpine-keys alpine-release alpine-baselayout-data \
kmod openrc dbus util-linux blkid chrony sysfsutils ssl_client openssh ca-certificates-bundle \
alpine-keys ethtool e2fsprogs e2fsprogs-extra libudev-zero libudev-zero-helper parted grep \
busybox-mdev-openrc procps-ng net-tools coreutils doas sed gawk findutils bash shadow pciutils \
mkinitfs</pre>

=== Setup openrc services ===
<pre>for rc in boot/bootmisc boot/hostname boot/modules boot/sysctl boot/urandom boot/networking \
sysinit/devfs sysinit/hwdrivers sysinit/mdev sysinit/modules \
shutdown/mount-ro shutdown/killprocs \
default/dbus default/networking default/chronyd default/local; do
ln -s /etc/init.d/"${rc##*/}" /etc/runlevels/"$rc"
done</pre>

=== Setup fstab within the chroot ===
<pre>cp /etc/fstab /etc/fstab.orig
echo $(blkid /dev/sdb2 | sed 's/.*: //;s/ .*//;s/"//g') / \ \ \ \ ext4 rw,relatime 0 1 > /etc/fstab.new
echo $(blkid /dev/sdb1 | sed 's/.*: //;s/ .*//;s/"//g') /boot ext4 rw,relatime 0 2 >> /etc/fstab.new
cat /etc/fstab.orig >> /etc/fstab.new
cp /etc/fstab.new /etc/fstab</pre>

=== Setup networking ===
<pre>[ ! -d /etc/network ] mkdir -vp /etc/networking
cat <<EOF > /etc/network/interfaces
auto lo
iface lo inet loopback

auto eth0
iface eth0 inet dhcp

EOF</pre>

=== Set the root password ===
When the system boots it will require a root password. This differs from Alpine install media but that's not the objective of this guide. This guide is installing a ready system.

<pre>passwd</pre>

=== Enable login on UART ===
<pre>sed -i 's/^#ttyS0/ttyS0/' /etc/inittab</pre>

== Setting up the boot environment ==
All of the effort up to this point has come down to this. This portion of the guide will assume the kernel being installed is version 6.6.63-ky from the vendor.
=== Install the kernel ===
We created an archive for each method of obtaining a kernel. Now we need to unpack that archive in our buildroot.
<pre>cd /mnt
tar xzf /var/tmp/linux-6.6.63-ky.tgz</pre>
=== Install the esos.elf firmware ===
Copy esos.elf from your very safe place to /mnt/lib/firmware
<pre>doas cp ~/Downloads/esos.elf /mnt/lib/firmware/</pre>
=== Creating the initrd image ===
The methods to obtain a kernel omitted collecting initrd images. Those images would not have been based on Alpine. We'll be using <code>mkinitfs</code> to do this. There are a few modifications we need to make in order for this process to generate an image with all the required bits.
==== Configuring and fixing mkinitfs ====
===== Add esos.elf to mkinitfs/features.d/base.files =====
<pre>echo "/lib/firmware/esos.elf" >> /etc/mkinitfs/features.d/base.files</pre>
===== Add the wireless-regdb database files to base.files =====
{{Note|
You may not need this. If you see a kernel message regarding failure to load regulatory.db with error -2, this will resolve it. Requires install of wireless-regdb apk package.}}
<pre>echo "/lib/firmware/regulatory.*" >> /etc/mkinitfs/features.d/base.files</pre>
===== Add jdb2 to ext4 =====
The ext4 module depends on the jdb2 module for filesystem journaling. The Alpine kernel does not have ext4 or jbd2 as kernel builtins. If you're using the Alpine provided kernel then you'll need this on the initramfs.
<pre>echo "kernel/fs/jbd2" >> /etc/mkinitfs/features.d/ext4.modules</pre>
===== Prevent mkinitfs from deleting needed firmware =====
The mkinitfs script will delete a directory that shouldn't exist. The files assembled from the features.d includes will have already been staged prior to mkinitfs assembling firmware needed by included modules. We need this not to happen and below is the simplest workaround I could pull together.
Make a copy of mkinitfs
<pre>cp /sbin/mkinitfs /sbin/mkinitfs-rv2</pre>
In the initfs_firmware function of <code>/sbin/mkinitfs-rv2</code> you will find the following lines
<pre> rm -rf "$tmpdir"/lib/firmware
mkdir -p "$tmpdir"/lib/firmware</pre>
Change them to be
<pre> #rm -rf "$tmpdir"/lib/firmware
[ ! -d "$tmpdir"/lib/firmware ] && mkdir -p "$tmpdir"/lib/firmware</pre>

==== Using mkinitfs-rv2 to create an initrd image ====
Installing from an Alpine host
<pre>mkinitfs-rv2 -b /mnt -c /mnt/etc/mkinitfs/mkinitfs.conf -o /mnt/boot/initramfs-6.6.63-ky 6.6.63-ky</pre>

Installing within a chroot
<pre>mkinitfs-rv2 -c /etc/mkinitfs/mkinitfs.conf -o /boot/initramfs-6.6.63-ky 6.6.63-ky</pre>
=== Configure extlinux ===
Create an extlinux.conf file with the following
<pre>default l0
menu title Alpine U-Boot menu
prompt 1
timeout 10

label l0
menu label Alpine Linux 3.24.0_alpha20260127 (Kernel 6.6.63-ky)
linux /vmlinuz-6.6.63-ky
initrd /initramfs-6.6.63-ky
fdt /dtb-6.6.63-ky/ky/x1_orangepi-rv2.dtb
append mtdparts=d420c000.spi-0:64K@0(bootinfo),64K@64K(private),256K@128K(fsbl),64K@384K(env),192K@448K(opensbi),-@640K(uboot) root=UUID=236a5824-0390-42dc-83e3-f02123188f96 console=ttyS0,115200 console=tty1 rootwait rw rootfstype=ext4 earlycon=sbi</pre>

==== A few notes on extlinux.conf ====
* Most device trees are generated in a dtbs/[kernel-version] directory.
* The vendor vmlinuz is a decompressed kernel image, though it shouldn't matter
* The mtdparts kernel parameter isn't absolutely required
* If using a kernel without ext4 and jbd2 modules as builtins, you'll need to append modules=ext4
* Only the right-most console statement seems to get attention. If you're on UART then you'll want <code>console=ttyS0,115200</code> and if you're on the framebuffer you'll want <code>console=tty1</code>.

== Wrapping Up ==

At this point the primary setup is complete. You may want to add some additional packages or configuration but can also be done after booting the RV2 board.

I may have forgotton something(s) which you'll soon discoven. I'll do my best to fold in corrections as I find they're needed or as new information becomes available.

=== Unmount the buildroot ===

<pre>umount /mnt/proc /mnt/sys /mnt/dev /mnt/boot /mnt</pre>

== Usability extras ==

The above should get your OrangePi RV2 booting Alpine Linux. Below are some additional configurations to help make growing your install a little easier. The following assumes you're still chroot /mnt or have booted the system.

=== Add a local user for yourself with escalation privileges ===

Create a user account for yourself with a secondary group of wheel
<pre># Create your account
useradd -G wheel -s /bin/bash -d /home/myuser -m -c "My User" myuser
# Set your password
passwd myuser</pre>

Add a configuration to doas.d for group wheel
<pre>echo permit persist :wheel > /etc/doas.d/00-wheel.conf</pre>

=== Install Avahi for mdns broadcasts ===

Avahi can broadcast names for services provided by your host. The default config in the Alpine package provides a configuration for sshd.

<pre># First setup the hostname
setup-hostname myhost

# Set the hostname
hostname `cat /etc/hostname`

# Install the avahi apk
apk add avahi

# Enable and start the avahi daemon
rc-update add avahi-daemon && rc-service avahi-daemon start</pre>

[[Category:Riscv64]]

Installing Alpine Linux on OrangePi RV2

2026-04-10T04:41:21Z

Aarch0x40:

{{Draft}}
[[Main Page]] > [[:Category:Architectures|Architectures]] > [[Riscv64]] > Installing Alpine Linux on OrangePi RV2
 
{{Warning|The contributors to the Alpine Linux project are not responsible for any damage/loss experienced by using the following guide. This article is provided as a general reference. It is assumed that the implementer will have the knowledge and ability to close the gap between what is described here and their specific setup.}}

The [http://www.orangepi.org/html/hardWare/computerAndMicrocontrollers/details/Orange-Pi-RV2.html OrangePi RV2] is a credit-card sized development board with a Ky X1 8-Core SoC. The Ky X1 is for all intents and purposes a SpacemiT K1 SoC. The remainder of this guide is more likely to use the terms SpacemiT or K1 as is prevalent throughout the Linux community. Please understand that these terms all refer to the same RISC-V ISA implementation.

This guide assumes that the manufacturer provided [https://github.com/riscv-software-src/opensbi OpenSBI] and [https://u-boot.org/ U-Boot] binaries have been applied to the SPI Flash device. This stock bootloader will look for an <code>extlinux/extlinux.conf</code> which will be used to configure the boot process.

Those following this guide may find it useful to have a USB UART serial cable available to debug kernel loading.

This guide borrows heavily from the article [https://arvanta.net/alpine/install-alpine-riscv64-qemu-uboot/ install Alpine Linux riscv64 under qemu with u-boot loader] by Milan P. Stanić and posted to [[Riscv64]] by [[User:AnIDFB]].

== Known issues ==
 
{{Warning|The following are the issues that are known to exist between the result of this guide and the manufacturer provided image}}

* Wireless (Wi-Fi & Bluetooth) is not functional
* Some kernel sources have an issue with starting the framebuffer
* Manufacturer tools are not included

This guide was assembled as a dumping of my personal notes. It's being updated as I come across new information. Alpine does run on the RV2 albeit not directly out of the box. Will do my best to reference external materials so that this article may provide some insight to others while still under development. The above may not be the only issues but hopefully there's enough information here to get you going.

== Kernel and Firmware ==
There are a few different options for kernels. The extent of coverage documented here is largely due to my initial ignorance. I have found a few sources for mostly workable kernels. None of them works 100%. SpacemiT is still in the process upstreaming functionality.

=== Obtaining the ESOS firmware ===
The processor being used on the RV2 requires a firmware to function properly. This file is available from the vendor images, in third party distributions and in the [https://github.com/orangepi-xunlong/orangepi-build orangepi-xunlong/orangepi-build] GitHub repository. The subdirectory containing the required file is [https://github.com/orangepi-xunlong/orangepi-build/tree/next/external/packages/bsp/ky/usr/lib/firmware external/packages/bsp/ky/usr/lib/firmware]. Download the file <code>esos.elf</code>. Keep the download in a safe place and also <code>/lib/firmware</code>. The <code>/lib/firmware</code> directory is also where you'll find this file within the vendor's image or an initrd image.
{{Note|
Changes to mkinitfs will be needed in order for this firmware to be included. More information on that will be provided further down the document}}
=== Obtaining the Vendor kernel ===
Open a browser to the [http://www.orangepi.org/html/hardWare/computerAndMicrocontrollers/service-and-support/Orange-Pi-RV2.html OrangePI RV2 Download] page.

Click on the "Downloads" button for the Ubuntu Image. This will take you to a Google Drive folder. Download the Orangepirv2_1.0.0_ubuntu_noble_server_linux6.6.63.7z.

Decompress this file after downloading using your favorite archive utility. It will expand to a directory containing Orangepirv2_1.0.0_ubuntu_noble_server_linux6.6.63.img and shasum file.

Attach the image to a loop device and mount the root partition.
<pre># Find the first available loop device
doas losetup --find

# Assuming the first found available device is /dev/loop0
doas losetup -P /dev/loop0 Orangepirv2_1.0.0_ubuntu_noble_server_linux6.6.63.img

# Mount the root slice
doas mount /dev/loop0p1 /mnt
</pre>

Archive the vendor kernel
<pre>cd /mnt
tar czf /var/tmp/linux-6.6.63-ky.tgz boot/vmlinuz-6.6.63-ky boot/System.map-6.6.63-ky boot/config-6.6.63-ky boot/dtb-6.6.63-ky lib/modules/6.6.63-ky</pre>
{{Note|
You probably want to put the resulting archive in a safer place than /var/tmp at this point. There's a bit to do before we'll need it.}}

Unmount and detach the vendor image
<pre>cd -
doas umount /mnt
doas losetup -d /dev/loop0</pre>
=== Will Alpine's kernel work? (TBD) ===
{{Note|
Need to revisit this}}
=== Building from source ===
There have been 2 main repositories for patched kernel sources.

* [https://github.com/jasonmontleon/linux-spacemit jasonmontleon/linux-spacemit]
* [https://github.com/BredOS/linux-bredos BredOS/linux-bredos]

The linux-spacemit repository is used by RedHat employee Jason Montleon in building out their RISCV64 support. The linux-bredos repository is used by the BredOS project which supports the RV2 and has provides downloadable images for the board. There is cross contribution between these two repositories. A lot of what I've learned to assemble this guide is attributed to these projects.

==== Setting up a workspace ====

Begin by setting up a RISC-V workspace by following [[Riscv64|Running Alpine riscv64 in QEMU]]. You'll need to establish a build environment in this QEMU guest.

<pre>doas apk add alpine-sdk bison flex openssl-dev ncurses ncurses-dev</pre>

{{Note|
<code>ncurses</code> and <code>ncurses-dev</code> aren't a hard requirements but are useful if you want to run <code>make menuconfig</code>}}

==== Cloning the source, configuring and building the kernel ====

{{Note|
This is needs a redo.}}

== Preparing the media ==

=== Partition and setup the filesystems ===
==== Install parted package ====
<pre>doas apk add parted</pre>
==== Insert, partition and format the boot media ====

The media can be either an SD card or USB drive. An 2280 PCIe NVMe is also possibly if you have the ability to write it from the host setting up the media. For the purposes of this guide we will refer to our boot media as <code>/dev/sdb</code>. The following section requires a root shell.

<pre>alias p="parted -sa optimal /dev/sdb"
p mklabel gpt
p mkpart boot ext4 0G 512M
p set 1 boot
p mkpart root ext4 512M 100%
p p</pre>

The final command should produce output to confirm the result of the executed commands. It should look something like the following.

<pre>Model: Generic STORAGE DEVICE (scsi)
Disk /dev/sdb: 15.5GB
Sector size (logical/physical): 512B/512B
Partition Table: gpt
Disk Flags:

Number Start End Size File system Name Flags
1 1049kB 512MB 511MB ext4 boot boot, esp
2 512MB 15.5GB 15.0GB root
</pre>

If all looks good, then we can proceed with formatting the partitions

<pre>mkfs.ext4 /dev/sdb1 && mkfs.ext4 /dev/sdb2</pre>

Mount the filesystems and lay some preliminary groundwork.

<pre># Mount the target root slice
mount /dev/sdb2 /mnt

# Create mount point for boot slice
[ ! -d /mnt/boot ] && mkdir -vp /mnt/boot

# Mount boot slice
mount /dev/sdb1 /mnt/boot

# Create directory for extlinux config
[ ! -d /mnt/boot/extlinux ] && mkdir -vp /mnt/boot/extlinux

# Create directory for apk config
[ ! -d /mnt/etc/apk ] && mkdir -vp /mnt/etc/apk

# Create mount point for devfs
[ ! -d /mnt/dev ] && mkdir -vp /mnt/dev

# Create mount point for procfs
[ ! -d /mnt/proc ] && mkdir -vp /mnt/proc

# Create mount point for sysfs
[ ! -d /mnt/sys ] && mkdir -vp /mnt/sys

# Use bind mounts for dev proc and sys within the target device
mount -o bind /dev /mnt/dev && mount -o bind /proc /mnt/proc && mount -o bind /sys /mnt/sys

# Configure apk package manager
cat <<EOF > /mnt/etc/apk/repositories
#/media/vda1/apks
http://dl-cdn.alpinelinux.org/alpine/edge/main
http://dl-cdn.alpinelinux.org/alpine/edge/community
http://dl-cdn.alpinelinux.org/alpine/edge/testing
EOF
</pre>
== Install Alpine from an Alpine host ==

=== Install Alpine with apk ===
Some of what is going to be installed is up to your choosing. This should be enough to get you going and demonstrate how to target an apk installation.
<pre>apk --root /mnt --arch riscv64 --allow-untrusted --initdb add \
alpine-base alpine-baselayout alpine-conf alpine-keys alpine-release alpine-baselayout-data \
kmod openrc dbus util-linux blkid chrony sysfsutils ssl_client openssh ca-certificates-bundle \
alpine-keys ethtool e2fsprogs e2fsprogs-extra libudev-zero libudev-zero-helper parted grep \
busybox-mdev-openrc procps-ng net-tools coreutils doas sed gawk findutils bash shadow pciutils \
mkinitfs</pre>

=== Setup openrc services ===
<pre>for rc in boot/bootmisc boot/hostname boot/modules boot/sysctl boot/urandom boot/networking \
sysinit/devfs sysinit/hwdrivers sysinit/mdev sysinit/modules \
shutdown/mount-ro shutdown/killprocs \
default/dbus default/networking default/chronyd default/local; do
ln -s /etc/init.d/"${rc##*/}" /mnt/etc/runlevels/"$rc"
done</pre>

=== Setup fstab ===
<pre>cp /mnt/etc/fstab /mnt/etc/fstab.orig
echo $(blkid /dev/sdb2 | sed 's/.*: //;s/ .*//;s/"//g') / \ \ \ \ ext4 rw,relatime 0 1 > /mnt/etc/fstab.new
echo $(blkid /dev/sdb1 | sed 's/.*: //;s/ .*//;s/"//g') /boot ext4 rw,relatime 0 2 >> /mnt/etc/fstab.new
cat /mnt/etc/fstab.orig >> /mnt/etc/fstab.new
cp /mnt/etc/fstab.new /mnt/etc/fstab</pre>

=== Setup networking ===
<pre>[ ! -d /mnt/etc/network ] mkdir -vp /mnt/etc/networking
cat <<EOF > /mnt/etc/network/interfaces
auto lo
iface lo inet loopback

auto eth0
iface eth0 inet dhcp

EOF</pre>

=== Set the root password ===
When the system boots it will require a root password. This differs from Alpine install media but that's not the objective of this guide. This guide is installing a ready system.

<pre>passwd -R /mnt root</pre>

=== Enable login on UART ===
<pre>sed -i 's/^#ttyS0/ttyS0/' /mnt/etc/inittab</pre>

== Install Alpine from an non-Alpine RISC-V Linux host ==
This section is mainly intended for those trying to install Alpine from one of the vendor images or another RISCV64 install. The apk utility does need to be able to run post-build scripts in order for target installation to function properly.

=== Download a minirootfs to run apk within a chroot ===
<pre>cd /var/tmp
wget https://dl-cdn.alpinelinux.org/edge/releases/riscv64/alpine-minirootfs-20260127-riscv64.tar.gz</pre>
Unzip in /mnt
<pre>cd /mnt
tar xfpz /var/tmp/alpine-minirootfs-20260127-riscv64.tar.gz</pre>
{{Note|
If installing from a non-Alpine host, you may want to install the kernel image and modules first. Come back to this part to chroot and run the apk step and finish up with mkinitfs}}
Chroot into /mnt and run <code>apk add</code>
<pre>chroot /mnt /bin/sh
apk --arch riscv64 --allow-untrusted --initdb add \
alpine-base alpine-baselayout alpine-conf alpine-keys alpine-release alpine-baselayout-data \
kmod openrc dbus util-linux blkid chrony sysfsutils ssl_client openssh ca-certificates-bundle \
alpine-keys ethtool e2fsprogs e2fsprogs-extra libudev-zero libudev-zero-helper parted grep \
busybox-mdev-openrc procps-ng net-tools coreutils doas sed gawk findutils bash shadow pciutils \
mkinitfs</pre>

=== Setup openrc services ===
<pre>for rc in boot/bootmisc boot/hostname boot/modules boot/sysctl boot/urandom boot/networking \
sysinit/devfs sysinit/hwdrivers sysinit/mdev sysinit/modules \
shutdown/mount-ro shutdown/killprocs \
default/dbus default/networking default/chronyd default/local; do
ln -s /etc/init.d/"${rc##*/}" /etc/runlevels/"$rc"
done</pre>

=== Setup fstab within the chroot ===
<pre>cp /etc/fstab /etc/fstab.orig
echo $(blkid /dev/sdb2 | sed 's/.*: //;s/ .*//;s/"//g') / \ \ \ \ ext4 rw,relatime 0 1 > /etc/fstab.new
echo $(blkid /dev/sdb1 | sed 's/.*: //;s/ .*//;s/"//g') /boot ext4 rw,relatime 0 2 >> /etc/fstab.new
cat /etc/fstab.orig >> /etc/fstab.new
cp /etc/fstab.new /etc/fstab</pre>

=== Setup networking ===
<pre>[ ! -d /etc/network ] mkdir -vp /etc/networking
cat <<EOF > /etc/network/interfaces
auto lo
iface lo inet loopback

auto eth0
iface eth0 inet dhcp

EOF</pre>

=== Set the root password ===
When the system boots it will require a root password. This differs from Alpine install media but that's not the objective of this guide. This guide is installing a ready system.

<pre>passwd</pre>

=== Enable login on UART ===
<pre>sed -i 's/^#ttyS0/ttyS0/' /etc/inittab</pre>

== Setting up the boot environment ==
All of the effort up to this point has come down to this. This portion of the guide will assume the kernel being installed is version 6.6.63-ky from the vendor.
=== Install the kernel ===
We created an archive for each method of obtaining a kernel. Now we need to unpack that archive in our buildroot.
<pre>cd /mnt
tar xzf /var/tmp/linux-6.6.63-ky.tgz</pre>
=== Install the esos.elf firmware ===
Copy esos.elf from your very safe place to /mnt/lib/firmware
<pre>doas cp ~/Downloads/esos.elf /mnt/lib/firmware/</pre>
=== Creating the initrd image ===
The methods to obtain a kernel omitted collecting initrd images. Those images would not have been based on Alpine. We'll be using <code>mkinitfs</code> to do this. There are a few modifications we need to make in order for this process to generate an image with all the required bits.
==== Configuring and fixing mkinitfs ====
===== Add esos.elf to mkinitfs/features.d/base.files =====
<pre>echo "/lib/firmware/esos.elf" >> /etc/mkinitfs/features.d/base.files</pre>
===== Add the wireless-regdb database files to base.files =====
{{Note|
You may not need this. If you see a kernel message regarding failure to load regulatory.db with error -2, this will resolve it. Requires install of wireless-regdb apk package.}}
<pre>echo "/lib/firmware/regulatory.*" >> /etc/mkinitfs/features.d/base.files</pre>
===== Add jdb2 to ext4 =====
The ext4 module depends on the jdb2 module for filesystem journaling. The Alpine kernel does not have ext4 or jbd2 as kernel builtins. If you're using the Alpine provided kernel then you'll need this on the initramfs.
<pre>echo "kernel/fs/jbd2" >> /etc/mkinitfs/features.d/ext4.modules</pre>
===== Prevent mkinitfs from deleting needed firmware =====
The mkinitfs script will delete a directory that shouldn't exist. The files assembled from the features.d includes will have already been staged prior to mkinitfs assembling firmware needed by included modules. We need this not to happen and below is the simplest workaround I could pull together.
Make a copy of mkinitfs
<pre>cp /sbin/mkinitfs /sbin/mkinitfs-rv2</pre>
In the initfs_firmware function of <code>/sbin/mkinitfs-rv2</code> you will find the following lines
<pre> rm -rf "$tmpdir"/lib/firmware
mkdir -p "$tmpdir"/lib/firmware</pre>
Change them to be
<pre> #rm -rf "$tmpdir"/lib/firmware
[ ! -d "$tmpdir"/lib/firmware ] && mkdir -p "$tmpdir"/lib/firmware</pre>

==== Using mkinitfs-rv2 to create an initrd image ====
Installing from an Alpine host
<pre>mkinitfs-rv2 -b /mnt -c /mnt/etc/mkinitfs/mkinitfs.conf -o /mnt/boot/initramfs-6.6.63-ky 6.6.63-ky</pre>

Installing within a chroot
<pre>mkinitfs-rv2 -c /etc/mkinitfs/mkinitfs.conf -o /boot/initramfs-6.6.63-ky 6.6.63-ky</pre>
=== Configure extlinux ===
Create an extlinux.conf file with the following
<pre>default l0
menu title Alpine U-Boot menu
prompt 1
timeout 10

label l0
menu label Alpine Linux 3.24.0_alpha20260127 (Kernel 6.17.0-spacemit-k1)
linux /vmlinuz-6.6.63-ky
initrd /initramfs-6.6.63-ky
fdt /dtb-6.6.63-ky/ky/x1_orangepi-rv2.dtb
append mtdparts=d420c000.spi-0:64K@0(bootinfo),64K@64K(private),256K@128K(fsbl),64K@384K(env),192K@448K(opensbi),-@640K(uboot) root=UUID=236a5824-0390-42dc-83e3-f02123188f96 console=ttyS0,115200 console=tty1 rootwait rw rootfstype=ext4 earlycon=sbi</pre>

==== A few notes on extlinux.conf ====
* Most device trees are generated in a dtbs/[kernel-version] directory.
* The vendor vmlinuz is a decompressed kernel image, though it shouldn't matter
* The mtdparts kernel parameter isn't absolutely required
* If using a kernel without ext4 and jbd2 modules as builtins, you'll need to append modules=ext4
* Only the right-most console statement seems to get attention. If you're on UART then you'll want <code>console=ttyS0,115200</code> and if you're on the framebuffer you'll want <code>console=tty1</code>.

== Wrapping Up ==

At this point the primary setup is complete. You may want to add some additional packages or configuration but can also be done after booting the RV2 board.

I may have forgotton something(s) which you'll soon discoven. I'll do my best to fold in corrections as I find they're needed or as new information becomes available.

=== Unmount the buildroot ===

<pre>umount /mnt/proc /mnt/sys /mnt/dev /mnt/boot /mnt</pre>

== Usability extras ==

The above should get your OrangePi RV2 booting Alpine Linux. Below are some additional configurations to help make growing your install a little easier. The following assumes you're still chroot /mnt or have booted the system.

=== Add a local user for yourself with escalation privileges ===

Create a user account for yourself with a secondary group of wheel
<pre># Create your account
useradd -G wheel -s /bin/bash -d /home/myuser -m -c "My User" myuser
# Set your password
passwd myuser</pre>

Add a configuration to doas.d for group wheel
<pre>echo permit persist :wheel > /etc/doas.d/00-wheel.conf</pre>

=== Install Avahi for mdns broadcasts ===

Avahi can broadcast names for services provided by your host. The default config in the Alpine package provides a configuration for sshd.

<pre># First setup the hostname
setup-hostname myhost

# Set the hostname
hostname `cat /etc/hostname`

# Install the avahi apk
apk add avahi

# Enable and start the avahi daemon
rc-update add avahi-daemon && rc-service avahi-daemon start</pre>

[[Category:Riscv64]]

Installing Alpine Linux on OrangePi RV2

2026-04-10T04:02:29Z

Aarch0x40:

{{Draft}}
[[Main Page]] > [[:Category:Architectures|Architectures]] > [[Riscv64]] > Installing Alpine Linux on OrangePi RV2
 
{{Warning|The contributors to the Alpine Linux project are not responsible for any damage/loss experienced by using the following guide. This article is provided as a general reference. It is assumed that the implementer will have the knowledge and ability to close the gap between what is described here and their specific setup.}}

The [http://www.orangepi.org/html/hardWare/computerAndMicrocontrollers/details/Orange-Pi-RV2.html OrangePi RV2] is a credit-card sized development board with a Ky X1 8-Core SoC. The Ky X1 is for all intents and purposes a SpacemiT K1 SoC. The remainder of this guide is more likely to use the terms SpacemiT or K1 as is prevalent throughout the Linux community. Please understand that these terms all refer to the same RISC-V ISA implementation.

This guide assumes that the manufacturer provided [https://github.com/riscv-software-src/opensbi OpenSBI] and [https://u-boot.org/ U-Boot] binaries have been applied to the SPI Flash device. This stock bootloader will look for an <code>extlinux/extlinux.conf</code> which will be used to configure the boot process.

Those following this guide may find it useful to have a USB UART serial cable available to debug kernel loading.

This guide borrows heavily from the article [https://arvanta.net/alpine/install-alpine-riscv64-qemu-uboot/ install Alpine Linux riscv64 under qemu with u-boot loader] by Milan P. Stanić and posted to [[Riscv64]] by [[User:AnIDFB]].

== Known issues ==
 
{{Warning|The following are the issues that are known to exist between the result of this guide and the manufacturer provided image}}

* Wireless (Wi-Fi & Bluetooth) is not functional
* Some kernel sources have an issue with starting the framebuffer
* Manufacturer tools are not included

This guide was assembled as a dumping of my personal notes. It's being updated as I come across new information. Alpine does run on the RV2 albeit not directly out of the box. Will do my best to reference external materials so that this article may provide some insight to others while still under development. The above may not be the only issues but hopefully there's enough information here to get you going.

== Kernel and Firmware ==
There are a few different options for kernels. The extent of coverage documented here is largely due to my initial ignorance. I have found a few sources for mostly workable kernels. None of them works 100%. SpacemiT is still in the process upstreaming functionality.

=== Obtaining the ESOS firmware ===
The processor being used on the RV2 requires a firmware to function properly. This file is available from the vendor images, in third party distributions and in the [https://github.com/orangepi-xunlong/orangepi-build orangepi-xunlong/orangepi-build] GitHub repository. The subdirectory containing the required file is [https://github.com/orangepi-xunlong/orangepi-build/tree/next/external/packages/bsp/ky/usr/lib/firmware external/packages/bsp/ky/usr/lib/firmware]. Download the file <code>esos.elf</code>. Keep the download in a safe place and also <code>/lib/firmware</code>. The <code>/lib/firmware</code> directory is also where you'll find this file within the vendor's image or an initrd image.
{{Note|
Changes to mkinitfs will be needed in order for this firmware to be included. More information on that will be provided further down the document}}
=== Obtaining the Vendor kernel ===
Open a browser to the [http://www.orangepi.org/html/hardWare/computerAndMicrocontrollers/service-and-support/Orange-Pi-RV2.html OrangePI RV2 Download] page.

Click on the "Downloads" button for the Ubuntu Image. This will take you to a Google Drive folder. Download the Orangepirv2_1.0.0_ubuntu_noble_server_linux6.6.63.7z.

Decompress this file after downloading using your favorite archive utility. It will expand to a directory containing Orangepirv2_1.0.0_ubuntu_noble_server_linux6.6.63.img and shasum file.

Attach the image to a loop device and mount the root partition.
<pre># Find the first available loop device
doas losetup --find

# Assuming the first found available device is /dev/loop0
doas losetup -P /dev/loop0 Orangepirv2_1.0.0_ubuntu_noble_server_linux6.6.63.img

# Mount the root slice
doas mount /dev/loop0p1 /mnt
</pre>

Archive the vendor kernel
<pre>cd /mnt
tar czf /var/tmp/linux-6.6.63-ky.tgz boot/vmlinuz-6.6.63-ky boot/System.map-6.6.63-ky boot/config-6.6.63-ky boot/dtb-6.6.63-ky lib/modules/6.6.63-ky</pre>
{{Note|
You probably want to put the resulting archive in a safer place than /var/tmp at this point. There's a bit to do before we'll need it.}}

Unmount and detach the vendor image
<pre>cd -
doas umount /mnt
doas losetup -d /dev/loop0</pre>
=== Will Alpine's kernel work? (TBD) ===
{{Note|
Need to revisit this}}
=== Building from source ===
There have been 2 main repositories for patched kernel sources.

* [https://github.com/jasonmontleon/linux-spacemit jasonmontleon/linux-spacemit]
* [https://github.com/BredOS/linux-bredos BredOS/linux-bredos]

The linux-spacemit repository is used by RedHat employee Jason Montleon in building out their RISCV64 support. The linux-bredos repository is used by the BredOS project which supports the RV2 and has provides downloadable images for the board. There is cross contribution between these two repositories. A lot of what I've learned to assemble this guide is attributed to these projects.

==== Setting up a workspace ====

Begin by setting up a RISC-V workspace by following [[Riscv64|Running Alpine riscv64 in QEMU]]. You'll need to establish a build environment in this QEMU guest.

<pre>doas apk add alpine-sdk bison flex openssl-dev ncurses ncurses-dev</pre>

{{Note|
<code>ncurses</code> and <code>ncurses-dev</code> aren't a hard requirements but are useful if you want to run <code>make menuconfig</code>}}

==== Cloning the source, configuring and building the kernel ====

{{Note|
This is needs a redo.}}

== Preparing the media ==

=== Partition and setup the filesystems ===
==== Install parted package ====
<pre>doas apk add parted</pre>
==== Insert, partition and format the boot media ====

The media can be either an SD card or USB drive. An 2280 PCIe NVMe is also possibly if you have the ability to write it from the host setting up the media. For the purposes of this guide we will refer to our boot media as <code>/dev/sdb</code>. The following section requires a root shell.

<pre>alias p="parted -sa optimal /dev/sdb"
p mklabel gpt
p mkpart boot ext4 0G 512M
p set 1 boot
p mkpart root ext4 512M 100%
p p</pre>

The final command should produce output to confirm the result of the executed commands. It should look something like the following.

<pre>Model: Generic STORAGE DEVICE (scsi)
Disk /dev/sdb: 15.5GB
Sector size (logical/physical): 512B/512B
Partition Table: gpt
Disk Flags:

Number Start End Size File system Name Flags
1 1049kB 512MB 511MB ext4 boot boot, esp
2 512MB 15.5GB 15.0GB root
</pre>

If all looks good, then we can proceed with formatting the partitions

<pre>mkfs.ext4 /dev/sdb1 && mkfs.ext4 /dev/sdb2</pre>

Mount the filesystems and lay some preliminary groundwork.

<pre># Mount the target root slice
mount /dev/sdb2 /mnt

# Create mount point for boot slice
[ ! -d /mnt/boot ] && mkdir -vp /mnt/boot

# Mount boot slice
mount /dev/sdb1 /mnt/boot

# Create directory for extlinux config
[ ! -d /mnt/boot/extlinux ] && mkdir -vp /mnt/boot/extlinux

# Create directory for apk config
[ ! -d /mnt/etc/apk ] && mkdir -vp /mnt/etc/apk

# Create mount point for devfs
[ ! -d /mnt/dev ] && mkdir -vp /mnt/dev

# Create mount point for procfs
[ ! -d /mnt/proc ] && mkdir -vp /mnt/proc

# Create mount point for sysfs
[ ! -d /mnt/sys ] && mkdir -vp /mnt/sys

# Use bind mounts for dev proc and sys within the target device
mount -o bind /dev /mnt/dev && mount -o bind /proc /mnt/proc && mount -o bind /sys /mnt/sys

# Configure apk package manager
cat <<EOF > /mnt/etc/apk/repositories
#/media/vda1/apks
http://dl-cdn.alpinelinux.org/alpine/edge/main
http://dl-cdn.alpinelinux.org/alpine/edge/community
http://dl-cdn.alpinelinux.org/alpine/edge/testing
EOF
</pre>
== Install Alpine from an Alpine host ==

=== Install Alpine with apk ===
Some of what is going to be installed is up to your choosing. This should be enough to get you going and demonstrate how to target an apk installation.
<pre>apk --root /mnt --arch riscv64 --allow-untrusted --initdb add \
alpine-base alpine-baselayout alpine-conf alpine-keys alpine-release alpine-baselayout-data \
kmod openrc dbus util-linux blkid chrony sysfsutils ssl_client openssh ca-certificates-bundle \
alpine-keys ethtool e2fsprogs e2fsprogs-extra libudev-zero libudev-zero-helper parted grep \
busybox-mdev-openrc procps-ng net-tools coreutils doas sed gawk findutils bash shadow pciutils \
mkinitfs</pre>

=== Setup openrc services ===
<pre>for rc in boot/bootmisc boot/hostname boot/modules boot/sysctl boot/urandom boot/networking \
sysinit/devfs sysinit/hwdrivers sysinit/mdev sysinit/modules \
shutdown/mount-ro shutdown/killprocs \
default/dbus default/networking default/chronyd default/local; do
ln -s /etc/init.d/"${rc##*/}" /mnt/etc/runlevels/"$rc"
done</pre>

=== Setup fstab ===
<pre>cp /mnt/etc/fstab /mnt/etc/fstab.orig
echo $(blkid /dev/sdb2 | sed 's/.*: //;s/ .*//;s/"//g') / \ \ \ \ ext4 rw,relatime 0 1 > /mnt/etc/fstab.new
echo $(blkid /dev/sdb1 | sed 's/.*: //;s/ .*//;s/"//g') /boot ext4 rw,relatime 0 2 >> /mnt/etc/fstab.new
cat /mnt/etc/fstab.orig >> /mnt/etc/fstab.new
cp /mnt/etc/fstab.new /mnt/etc/fstab</pre>

=== Setup networking ===
<pre>[ ! -d /mnt/etc/network ] mkdir -vp /mnt/etc/networking
cat <<EOF > /mnt/etc/network/interfaces
auto lo
iface lo inet loopback

auto eth0
iface eth0 inet dhcp

EOF</pre>

=== Set the root password ===
When the system boots it will require a root password. This differs from Alpine install media but that's not the objective of this guide. This guide is installing a ready system.

<pre>passwd -R /mnt root</pre>

=== Enable login on UART ===
<pre>sed -i 's/^#ttyS0/ttyS0/' /mnt/etc/inittab</pre>

== Install Alpine from an non-Alpine RISC-V Linux host ==

=== Download a minirootfs to run apk within a chroot ===
<pre>cd /var/tmp
wget https://dl-cdn.alpinelinux.org/edge/releases/riscv64/alpine-minirootfs-20260127-riscv64.tar.gz</pre>
Unzip in /mnt
<pre>cd /mnt
tar xfpz /var/tmp/alpine-minirootfs-20260127-riscv64.tar.gz</pre>
{{Note|
If installing from a non-Alpine host, you may want to install the kernel image and modules first. Come back to this part to chroot and run the apk step and finish up with mkinitfs}}
Chroot into /mnt and run <code>apk add</code>
<pre>chroot /mnt /bin/sh
apk --arch riscv64 --allow-untrusted --initdb add \
alpine-base alpine-baselayout alpine-conf alpine-keys alpine-release alpine-baselayout-data \
kmod openrc dbus util-linux blkid chrony sysfsutils ssl_client openssh ca-certificates-bundle \
alpine-keys ethtool e2fsprogs e2fsprogs-extra libudev-zero libudev-zero-helper parted grep \
busybox-mdev-openrc procps-ng net-tools coreutils doas sed gawk findutils bash shadow pciutils \
mkinitfs</pre>

=== Setup openrc services ===
<pre>for rc in boot/bootmisc boot/hostname boot/modules boot/sysctl boot/urandom boot/networking \
sysinit/devfs sysinit/hwdrivers sysinit/mdev sysinit/modules \
shutdown/mount-ro shutdown/killprocs \
default/dbus default/networking default/chronyd default/local; do
ln -s /etc/init.d/"${rc##*/}" /etc/runlevels/"$rc"
done</pre>

=== Setup fstab within the chroot ===
<pre>cp /etc/fstab /etc/fstab.orig
echo $(blkid /dev/sdb2 | sed 's/.*: //;s/ .*//;s/"//g') / \ \ \ \ ext4 rw,relatime 0 1 > /etc/fstab.new
echo $(blkid /dev/sdb1 | sed 's/.*: //;s/ .*//;s/"//g') /boot ext4 rw,relatime 0 2 >> /etc/fstab.new
cat /etc/fstab.orig >> /etc/fstab.new
cp /etc/fstab.new /etc/fstab</pre>

=== Setup networking ===
<pre>[ ! -d /etc/network ] mkdir -vp /etc/networking
cat <<EOF > /etc/network/interfaces
auto lo
iface lo inet loopback

auto eth0
iface eth0 inet dhcp

EOF</pre>

=== Set the root password ===
When the system boots it will require a root password. This differs from Alpine install media but that's not the objective of this guide. This guide is installing a ready system.

<pre>passwd</pre>

=== Enable login on UART ===
<pre>sed -i 's/^#ttyS0/ttyS0/' /etc/inittab</pre>

== Setting up the boot environment ==
All of the effort up to this point has come down to this. This portion of the guide will assume the kernel being installed is version 6.6.63-ky from the vendor.
=== Install the kernel ===
=== Install the esos.elf firmware ===
=== Creating the initrd image ===
==== Configuring and fixing mkinitfs ====
===== Add esos.elf to mkinitfs/features.d/base.files =====
<pre>echo "/lib/firmware/esos.elf" >> /etc/mkinitfs/features.d/base.files</pre>
===== Add the wireless-regdb database files to base.files =====
{{Note|
You may not need this. If you see a kernel message regarding failure to load regulatory.db with error -2, this will resolve it}}
<pre>echo "/lib/firmware/regulatory.*" >> /etc/mkinitfs/features.d/base.files</pre>
===== Add jdb2 to ext4 =====
The ext4 module depends on the jdb2 module for filesystem journaling. The Alpine kernel does not have ext4 or jbd2 as kernel builtins. If you're using the Alpine provided kernel then you'll need this on the initramfs.
<pre>echo "kernel/fs/jbd2" >> /etc/mkinitfs/features.d/ext4.modules</pre>
===== Prevent mkinitfs from deleting needed firmware =====
The mkinitfs script will delete a directory that shouldn't exist. The files assembled from the features.d includes will have already been staged prior to mkinitfs assembling firmware needed by included modules. We need this not to happen and below is the simplest workaround I could pull together.
Make a copy of mkinitfs
<pre>cp /sbin/mkinitfs /sbin/mkinitfs-rv2</pre>
In the initfs_firmware function of <code>/sbin/mkinitfs-rv2</code> you will find the following lines
<pre> rm -rf "$tmpdir"/lib/firmware
mkdir -p "$tmpdir"/lib/firmware</pre>
Change them to be
<pre> #rm -rf "$tmpdir"/lib/firmware
[ ! -d "$tmpdir"/lib/firmware ] && mkdir -p "$tmpdir"/lib/firmware</pre>

==== Using mkinitfs-rv2 to create an initrd image ====
=== Configure extlinux ===

== Basic usability options ==

The above should get your OrangePi RV2 booting Alpine Linux. Below are some additional configurations to help make growing your install a little easier. The following assumes you're still chroot /mnt or have booted the system.

=== Add a local user for yourself with escalation privileges ===

Create a user account for yourself with a secondary group of wheel
<pre># Create your account
useradd -G wheel -s /bin/bash -d /home/myuser -m -c "My User" myuser
# Set your password
passwd myuser</pre>

Add a configuration to doas.d for group wheel
<pre>echo permit persist :wheel > /etc/doas.d/00-wheel.conf</pre>

=== Install Avahi for mdns broadcasts ===

Avahi can broadcast names for services provided by your host. The default config in the Alpine package provides a configuration for sshd.

<pre># First setup the hostname
setup-hostname myhost

# Set the hostname
hostname `cat /etc/hostname`

# Install the avahi apk
apk add avahi

# Enable and start the avahi daemon
rc-update add avahi-daemon && rc-service avahi-daemon start</pre>

[[Category:Riscv64]]

Installing Alpine Linux on OrangePi RV2

2026-04-10T04:00:17Z

Aarch0x40:

{{TOC left}}
{{Draft}}
[[Main Page]] > [[:Category:Architectures|Architectures]] > [[Riscv64]] > Installing Alpine Linux on OrangePi RV2
 
{{Warning|The contributors to the Alpine Linux project are not responsible for any damage/loss experienced by using the following guide. This article is provided as a general reference. It is assumed that the implementer will have the knowledge and ability to close the gap between what is described here and their specific setup.}}

The [http://www.orangepi.org/html/hardWare/computerAndMicrocontrollers/details/Orange-Pi-RV2.html OrangePi RV2] is a credit-card sized development board with a Ky X1 8-Core SoC. The Ky X1 is for all intents and purposes a SpacemiT K1 SoC. The remainder of this guide is more likely to use the terms SpacemiT or K1 as is prevalent throughout the Linux community. Please understand that these terms all refer to the same RISC-V ISA implementation.

This guide assumes that the manufacturer provided [https://github.com/riscv-software-src/opensbi OpenSBI] and [https://u-boot.org/ U-Boot] binaries have been applied to the SPI Flash device. This stock bootloader will look for an <code>extlinux/extlinux.conf</code> which will be used to configure the boot process.

Those following this guide may find it useful to have a USB UART serial cable available to debug kernel loading.

This guide borrows heavily from the article [https://arvanta.net/alpine/install-alpine-riscv64-qemu-uboot/ install Alpine Linux riscv64 under qemu with u-boot loader] by Milan P. Stanić and posted to [[Riscv64]] by [[User:AnIDFB]].

== Known issues ==
 
{{Warning|The following are the issues that are known to exist between the result of this guide and the manufacturer provided image}}

* Wireless (Wi-Fi & Bluetooth) is not functional
* Some kernel sources have an issue with starting the framebuffer
* Manufacturer tools are not included

This guide was assembled as a dumping of my personal notes. It's being updated as I come across new information. Alpine does run on the RV2 albeit not directly out of the box. Will do my best to reference external materials so that this article may provide some insight to others while still under development. The above may not be the only issues but hopefully there's enough information here to get you going.

== Kernel and Firmware ==
There are a few different options for kernels. The extent of coverage documented here is largely due to my initial ignorance. I have found a few sources for mostly workable kernels. None of them works 100%. SpacemiT is still in the process upstreaming functionality.

=== Obtaining the ESOS firmware ===
The processor being used on the RV2 requires a firmware to function properly. This file is available from the vendor images, in third party distributions and in the [https://github.com/orangepi-xunlong/orangepi-build orangepi-xunlong/orangepi-build] GitHub repository. The subdirectory containing the required file is [https://github.com/orangepi-xunlong/orangepi-build/tree/next/external/packages/bsp/ky/usr/lib/firmware external/packages/bsp/ky/usr/lib/firmware]. Download the file <code>esos.elf</code>. Keep the download in a safe place and also <code>/lib/firmware</code>. The <code>/lib/firmware</code> directory is also where you'll find this file within the vendor's image or an initrd image.
{{Note|
Changes to mkinitfs will be needed in order for this firmware to be included. More information on that will be provided further down the document}}
=== Obtaining the Vendor kernel ===
Open a browser to the [http://www.orangepi.org/html/hardWare/computerAndMicrocontrollers/service-and-support/Orange-Pi-RV2.html OrangePI RV2 Download] page.

Click on the "Downloads" button for the Ubuntu Image. This will take you to a Google Drive folder. Download the Orangepirv2_1.0.0_ubuntu_noble_server_linux6.6.63.7z.

Decompress this file after downloading using your favorite archive utility. It will expand to a directory containing Orangepirv2_1.0.0_ubuntu_noble_server_linux6.6.63.img and shasum file.

Attach the image to a loop device and mount the root partition.
<pre># Find the first available loop device
doas losetup --find

# Assuming the first found available device is /dev/loop0
doas losetup -P /dev/loop0 Orangepirv2_1.0.0_ubuntu_noble_server_linux6.6.63.img

# Mount the root slice
doas mount /dev/loop0p1 /mnt
</pre>

Archive the vendor kernel
<pre>cd /mnt
tar czf /var/tmp/linux-6.6.63-ky.tgz boot/vmlinuz-6.6.63-ky boot/System.map-6.6.63-ky boot/config-6.6.63-ky boot/dtb-6.6.63-ky lib/modules/6.6.63-ky</pre>
{{Note|
You probably want to put the resulting archive in a safer place than /var/tmp at this point. There's a bit to do before we'll need it.}}

Unmount and detach the vendor image
<pre>cd -
doas umount /mnt
doas losetup -d /dev/loop0</pre>
=== Will Alpine's kernel work? (TBD) ===
{{Note|
Need to revisit this}}
=== Building from source ===
There have been 2 main repositories for patched kernel sources.

* [https://github.com/jasonmontleon/linux-spacemit jasonmontleon/linux-spacemit]
* [https://github.com/BredOS/linux-bredos BredOS/linux-bredos]

The linux-spacemit repository is used by RedHat employee Jason Montleon in building out their RISCV64 support. The linux-bredos repository is used by the BredOS project which supports the RV2 and has provides downloadable images for the board. There is cross contribution between these two repositories. A lot of what I've learned to assemble this guide is attributed to these projects.

==== Setting up a workspace ====

Begin by setting up a RISC-V workspace by following [[Riscv64|Running Alpine riscv64 in QEMU]]. You'll need to establish a build environment in this QEMU guest.

<pre>doas apk add alpine-sdk bison flex openssl-dev ncurses ncurses-dev</pre>

{{Note|
<code>ncurses</code> and <code>ncurses-dev</code> aren't a hard requirements but are useful if you want to run <code>make menuconfig</code>}}

==== Cloning the source, configuring and building the kernel ====

{{Note|
This is needs a redo.}}

== Preparing the media ==

=== Partition and setup the filesystems ===
==== Install parted package ====
<pre>doas apk add parted</pre>
==== Insert, partition and format the boot media ====

The media can be either an SD card or USB drive. An 2280 PCIe NVMe is also possibly if you have the ability to write it from the host setting up the media. For the purposes of this guide we will refer to our boot media as <code>/dev/sdb</code>. The following section requires a root shell.

<pre>alias p="parted -sa optimal /dev/sdb"
p mklabel gpt
p mkpart boot ext4 0G 512M
p set 1 boot
p mkpart root ext4 512M 100%
p p</pre>

The final command should produce output to confirm the result of the executed commands. It should look something like the following.

<pre>Model: Generic STORAGE DEVICE (scsi)
Disk /dev/sdb: 15.5GB
Sector size (logical/physical): 512B/512B
Partition Table: gpt
Disk Flags:

Number Start End Size File system Name Flags
1 1049kB 512MB 511MB ext4 boot boot, esp
2 512MB 15.5GB 15.0GB root
</pre>

If all looks good, then we can proceed with formatting the partitions

<pre>mkfs.ext4 /dev/sdb1 && mkfs.ext4 /dev/sdb2</pre>

Mount the filesystems and lay some preliminary groundwork.

<pre># Mount the target root slice
mount /dev/sdb2 /mnt

# Create mount point for boot slice
[ ! -d /mnt/boot ] && mkdir -vp /mnt/boot

# Mount boot slice
mount /dev/sdb1 /mnt/boot

# Create directory for extlinux config
[ ! -d /mnt/boot/extlinux ] && mkdir -vp /mnt/boot/extlinux

# Create directory for apk config
[ ! -d /mnt/etc/apk ] && mkdir -vp /mnt/etc/apk

# Create mount point for devfs
[ ! -d /mnt/dev ] && mkdir -vp /mnt/dev

# Create mount point for procfs
[ ! -d /mnt/proc ] && mkdir -vp /mnt/proc

# Create mount point for sysfs
[ ! -d /mnt/sys ] && mkdir -vp /mnt/sys

# Use bind mounts for dev proc and sys within the target device
mount -o bind /dev /mnt/dev && mount -o bind /proc /mnt/proc && mount -o bind /sys /mnt/sys

# Configure apk package manager
cat <<EOF > /mnt/etc/apk/repositories
#/media/vda1/apks
http://dl-cdn.alpinelinux.org/alpine/edge/main
http://dl-cdn.alpinelinux.org/alpine/edge/community
http://dl-cdn.alpinelinux.org/alpine/edge/testing
EOF
</pre>
== Install Alpine from an Alpine host ==

=== Install Alpine with apk ===
Some of what is going to be installed is up to your choosing. This should be enough to get you going and demonstrate how to target an apk installation.
<pre>apk --root /mnt --arch riscv64 --allow-untrusted --initdb add \
alpine-base alpine-baselayout alpine-conf alpine-keys alpine-release alpine-baselayout-data \
kmod openrc dbus util-linux blkid chrony sysfsutils ssl_client openssh ca-certificates-bundle \
alpine-keys ethtool e2fsprogs e2fsprogs-extra libudev-zero libudev-zero-helper parted grep \
busybox-mdev-openrc procps-ng net-tools coreutils doas sed gawk findutils bash shadow pciutils \
mkinitfs</pre>

=== Setup openrc services ===
<pre>for rc in boot/bootmisc boot/hostname boot/modules boot/sysctl boot/urandom boot/networking \
sysinit/devfs sysinit/hwdrivers sysinit/mdev sysinit/modules \
shutdown/mount-ro shutdown/killprocs \
default/dbus default/networking default/chronyd default/local; do
ln -s /etc/init.d/"${rc##*/}" /mnt/etc/runlevels/"$rc"
done</pre>

=== Setup fstab ===
<pre>cp /mnt/etc/fstab /mnt/etc/fstab.orig
echo $(blkid /dev/sdb2 | sed 's/.*: //;s/ .*//;s/"//g') / \ \ \ \ ext4 rw,relatime 0 1 > /mnt/etc/fstab.new
echo $(blkid /dev/sdb1 | sed 's/.*: //;s/ .*//;s/"//g') /boot ext4 rw,relatime 0 2 >> /mnt/etc/fstab.new
cat /mnt/etc/fstab.orig >> /mnt/etc/fstab.new
cp /mnt/etc/fstab.new /mnt/etc/fstab</pre>

=== Setup networking ===
<pre>[ ! -d /mnt/etc/network ] mkdir -vp /mnt/etc/networking
cat <<EOF > /mnt/etc/network/interfaces
auto lo
iface lo inet loopback

auto eth0
iface eth0 inet dhcp

EOF</pre>

=== Set the root password ===
When the system boots it will require a root password. This differs from Alpine install media but that's not the objective of this guide. This guide is installing a ready system.

<pre>passwd -R /mnt root</pre>

=== Enable login on UART ===
<pre>sed -i 's/^#ttyS0/ttyS0/' /mnt/etc/inittab</pre>

== Install Alpine from an non-Alpine RISC-V Linux host ==

=== Download a minirootfs to run apk within a chroot ===
<pre>cd /var/tmp
wget https://dl-cdn.alpinelinux.org/edge/releases/riscv64/alpine-minirootfs-20260127-riscv64.tar.gz</pre>
Unzip in /mnt
<pre>cd /mnt
tar xfpz /var/tmp/alpine-minirootfs-20260127-riscv64.tar.gz</pre>
{{Note|
If installing from a non-Alpine host, you may want to install the kernel image and modules first. Come back to this part to chroot and run the apk step and finish up with mkinitfs}}
Chroot into /mnt and run <code>apk add</code>
<pre>chroot /mnt /bin/sh
apk --arch riscv64 --allow-untrusted --initdb add \
alpine-base alpine-baselayout alpine-conf alpine-keys alpine-release alpine-baselayout-data \
kmod openrc dbus util-linux blkid chrony sysfsutils ssl_client openssh ca-certificates-bundle \
alpine-keys ethtool e2fsprogs e2fsprogs-extra libudev-zero libudev-zero-helper parted grep \
busybox-mdev-openrc procps-ng net-tools coreutils doas sed gawk findutils bash shadow pciutils \
mkinitfs</pre>

=== Setup openrc services ===
<pre>for rc in boot/bootmisc boot/hostname boot/modules boot/sysctl boot/urandom boot/networking \
sysinit/devfs sysinit/hwdrivers sysinit/mdev sysinit/modules \
shutdown/mount-ro shutdown/killprocs \
default/dbus default/networking default/chronyd default/local; do
ln -s /etc/init.d/"${rc##*/}" /etc/runlevels/"$rc"
done</pre>

=== Setup fstab within the chroot ===
<pre>cp /etc/fstab /etc/fstab.orig
echo $(blkid /dev/sdb2 | sed 's/.*: //;s/ .*//;s/"//g') / \ \ \ \ ext4 rw,relatime 0 1 > /etc/fstab.new
echo $(blkid /dev/sdb1 | sed 's/.*: //;s/ .*//;s/"//g') /boot ext4 rw,relatime 0 2 >> /etc/fstab.new
cat /etc/fstab.orig >> /etc/fstab.new
cp /etc/fstab.new /etc/fstab</pre>

=== Setup networking ===
<pre>[ ! -d /etc/network ] mkdir -vp /etc/networking
cat <<EOF > /etc/network/interfaces
auto lo
iface lo inet loopback

auto eth0
iface eth0 inet dhcp

EOF</pre>

=== Set the root password ===
When the system boots it will require a root password. This differs from Alpine install media but that's not the objective of this guide. This guide is installing a ready system.

<pre>passwd</pre>

=== Enable login on UART ===
<pre>sed -i 's/^#ttyS0/ttyS0/' /etc/inittab</pre>

== Setting up the boot environment ==
All of the effort up to this point has come down to this. This portion of the guide will assume the kernel being installed is version 6.6.63-ky from the vendor.
=== Install the kernel ===
=== Install the esos.elf firmware ===
=== Creating the initrd image ===
==== Configuring and fixing mkinitfs ====
===== Add esos.elf to mkinitfs/features.d/base.files =====
<pre>echo "/lib/firmware/esos.elf" >> /etc/mkinitfs/features.d/base.files</pre>
===== Add the wireless-regdb database files to base.files =====
{{Note|
You may not need this. If you see a kernel message regarding failure to load regulatory.db with error -2, this will resolve it}}
<pre>echo "/lib/firmware/regulatory.*" >> /etc/mkinitfs/features.d/base.files</pre>
===== Add jdb2 to ext4 =====
The ext4 module depends on the jdb2 module for filesystem journaling. The Alpine kernel does not have ext4 or jbd2 as kernel builtins. If you're using the Alpine provided kernel then you'll need this on the initramfs.
<pre>echo "kernel/fs/jbd2" >> /etc/mkinitfs/features.d/ext4.modules</pre>
===== Prevent mkinitfs from deleting needed firmware =====
The mkinitfs script will delete a directory that shouldn't exist. The files assembled from the features.d includes will have already been staged prior to mkinitfs assembling firmware needed by included modules. We need this not to happen and below is the simplest workaround I could pull together.
Make a copy of mkinitfs
<pre>cp /sbin/mkinitfs /sbin/mkinitfs-rv2</pre>
In the initfs_firmware function of <code>/sbin/mkinitfs-rv2</code> you will find the following lines
<pre> rm -rf "$tmpdir"/lib/firmware
mkdir -p "$tmpdir"/lib/firmware</pre>
Change them to be
<pre> #rm -rf "$tmpdir"/lib/firmware
[ ! -d "$tmpdir"/lib/firmware ] && mkdir -p "$tmpdir"/lib/firmware</pre>

==== Using mkinitfs-rv2 to create an initrd image ====
=== Configure extlinux ===

== Basic usability options ==

The above should get your OrangePi RV2 booting Alpine Linux. Below are some additional configurations to help make growing your install a little easier. The following assumes you're still chroot /mnt or have booted the system.

=== Add a local user for yourself with escalation privileges ===

Create a user account for yourself with a secondary group of wheel
<pre># Create your account
useradd -G wheel -s /bin/bash -d /home/myuser -m -c "My User" myuser
# Set your password
passwd myuser</pre>

Add a configuration to doas.d for group wheel
<pre>echo permit persist :wheel > /etc/doas.d/00-wheel.conf</pre>

=== Install Avahi for mdns broadcasts ===

Avahi can broadcast names for services provided by your host. The default config in the Alpine package provides a configuration for sshd.

<pre># First setup the hostname
setup-hostname myhost

# Set the hostname
hostname `cat /etc/hostname`

# Install the avahi apk
apk add avahi

# Enable and start the avahi daemon
rc-update add avahi-daemon && rc-service avahi-daemon start</pre>

[[Category:Riscv64]]

Installing Alpine Linux on OrangePi RV2

2026-04-10T03:57:38Z

Aarch0x40:

{{TOC right}}
{{Draft}}
[[Main Page]] > [[:Category:Architectures|Architectures]] > [[Riscv64]] > Installing Alpine Linux on OrangePi RV2
 
{{Warning|The contributors to the Alpine Linux project are not responsible for any damage/loss experienced by using the following guide. This article is provided as a general reference. It is assumed that the implementer will have the knowledge and ability to close the gap between what is described here and their specific setup.}}

The [http://www.orangepi.org/html/hardWare/computerAndMicrocontrollers/details/Orange-Pi-RV2.html OrangePi RV2] is a credit-card sized development board with a Ky X1 8-Core SoC. The Ky X1 is for all intents and purposes a SpacemiT K1 SoC. The remainder of this guide is more likely to use the terms SpacemiT or K1 as is prevalent throughout the Linux community. Please understand that these terms all refer to the same RISC-V ISA implementation.

This guide assumes that the manufacturer provided [https://github.com/riscv-software-src/opensbi OpenSBI] and [https://u-boot.org/ U-Boot] binaries have been applied to the SPI Flash device. This stock bootloader will look for an <code>extlinux/extlinux.conf</code> which will be used to configure the boot process.

Those following this guide may find it useful to have a USB UART serial cable available to debug kernel loading.

This guide borrows heavily from the article [https://arvanta.net/alpine/install-alpine-riscv64-qemu-uboot/ install Alpine Linux riscv64 under qemu with u-boot loader] by Milan P. Stanić and posted to [[Riscv64]] by [[User:AnIDFB]].

== Known issues ==
 
{{Warning|The following are the issues that are known to exist between the result of this guide and the manufacturer provided image}}

* Wireless (Wi-Fi & Bluetooth) is not functional
* Some kernel sources have an issue with starting the framebuffer
* Manufacturer tools are not included

This guide was assembled as a dumping of my personal notes. It's being updated as I come across new information. Alpine does run on the RV2 albeit not directly out of the box. Will do my best to reference external materials so that this article may provide some insight to others while still under development. The above may not be the only issues but hopefully there's enough information here to get you going.

== Kernel and Firmware ==
There are a few different options for kernels. The extent of coverage documented here is largely due to my initial ignorance. I have found a few sources for mostly workable kernels. None of them works 100%. SpacemiT is still in the process upstreaming functionality.

=== Obtaining the ESOS firmware ===
The processor being used on the RV2 requires a firmware to function properly. This file is available from the vendor images, in third party distributions and in the [https://github.com/orangepi-xunlong/orangepi-build orangepi-xunlong/orangepi-build] GitHub repository. The subdirectory containing the required file is [https://github.com/orangepi-xunlong/orangepi-build/tree/next/external/packages/bsp/ky/usr/lib/firmware external/packages/bsp/ky/usr/lib/firmware]. Download the file <code>esos.elf</code>. Keep the download in a safe place and also <code>/lib/firmware</code>. The <code>/lib/firmware</code> directory is also where you'll find this file within the vendor's image or an initrd image.
{{Note|
Changes to mkinitfs will be needed in order for this firmware to be included. More information on that will be provided further down the document}}
=== Obtaining the Vendor kernel ===
Open a browser to the [http://www.orangepi.org/html/hardWare/computerAndMicrocontrollers/service-and-support/Orange-Pi-RV2.html OrangePI RV2 Download] page.

Click on the "Downloads" button for the Ubuntu Image. This will take you to a Google Drive folder. Download the Orangepirv2_1.0.0_ubuntu_noble_server_linux6.6.63.7z.

Decompress this file after downloading using your favorite archive utility. It will expand to a directory containing Orangepirv2_1.0.0_ubuntu_noble_server_linux6.6.63.img and shasum file.

Attach the image to a loop device and mount the root partition.
<pre># Find the first available loop device
doas losetup --find

# Assuming the first found available device is /dev/loop0
doas losetup -P /dev/loop0 Orangepirv2_1.0.0_ubuntu_noble_server_linux6.6.63.img

# Mount the root slice
doas mount /dev/loop0p1 /mnt
</pre>

Archive the vendor kernel
<pre>cd /mnt
tar czf /var/tmp/linux-6.6.63-ky.tgz boot/vmlinuz-6.6.63-ky boot/System.map-6.6.63-ky boot/config-6.6.63-ky boot/dtb-6.6.63-ky lib/modules/6.6.63-ky</pre>
{{Note|
You probably want to put the resulting archive in a safer place than /var/tmp at this point. There's a bit to do before we'll need it.}}

Unmount and detach the vendor image
<pre>cd -
doas umount /mnt
doas losetup -d /dev/loop0</pre>
=== Will Alpine's kernel work? (TBD) ===
{{Note|
Need to revisit this}}
=== Building from source ===
There have been 2 main repositories for patched kernel sources.

* [https://github.com/jasonmontleon/linux-spacemit jasonmontleon/linux-spacemit]
* [https://github.com/BredOS/linux-bredos BredOS/linux-bredos]

The linux-spacemit repository is used by RedHat employee Jason Montleon in building out their RISCV64 support. The linux-bredos repository is used by the BredOS project which supports the RV2 and has provides downloadable images for the board. There is cross contribution between these two repositories. A lot of what I've learned to assemble this guide is attributed to these projects.

==== Setting up a workspace ====

Begin by setting up a RISC-V workspace by following [[Riscv64|Running Alpine riscv64 in QEMU]]. You'll need to establish a build environment in this QEMU guest.

<pre>doas apk add alpine-sdk bison flex openssl-dev ncurses ncurses-dev</pre>

{{Note|
<code>ncurses</code> and <code>ncurses-dev</code> aren't a hard requirements but are useful if you want to run <code>make menuconfig</code>}}

==== Cloning the source, configuring and building the kernel ====

{{Note|
This is needs a redo.}}

== Preparing the media ==

=== Partition and setup the filesystems ===
==== Install parted package ====
<pre>doas apk add parted</pre>
==== Insert, partition and format the boot media ====

The media can be either an SD card or USB drive. An 2280 PCIe NVMe is also possibly if you have the ability to write it from the host setting up the media. For the purposes of this guide we will refer to our boot media as <code>/dev/sdb</code>. The following section requires a root shell.

<pre>alias p="parted -sa optimal /dev/sdb"
p mklabel gpt
p mkpart boot ext4 0G 512M
p set 1 boot
p mkpart root ext4 512M 100%
p p</pre>

The final command should produce output to confirm the result of the executed commands. It should look something like the following.

<pre>Model: Generic STORAGE DEVICE (scsi)
Disk /dev/sdb: 15.5GB
Sector size (logical/physical): 512B/512B
Partition Table: gpt
Disk Flags:

Number Start End Size File system Name Flags
1 1049kB 512MB 511MB ext4 boot boot, esp
2 512MB 15.5GB 15.0GB root
</pre>

If all looks good, then we can proceed with formatting the partitions

<pre>mkfs.ext4 /dev/sdb1 && mkfs.ext4 /dev/sdb2</pre>

Mount the filesystems and lay some preliminary groundwork.

<pre># Mount the target root slice
mount /dev/sdb2 /mnt

# Create mount point for boot slice
[ ! -d /mnt/boot ] && mkdir -vp /mnt/boot

# Mount boot slice
mount /dev/sdb1 /mnt/boot

# Create directory for extlinux config
[ ! -d /mnt/boot/extlinux ] && mkdir -vp /mnt/boot/extlinux

# Create directory for apk config
[ ! -d /mnt/etc/apk ] && mkdir -vp /mnt/etc/apk

# Create mount point for devfs
[ ! -d /mnt/dev ] && mkdir -vp /mnt/dev

# Create mount point for procfs
[ ! -d /mnt/proc ] && mkdir -vp /mnt/proc

# Create mount point for sysfs
[ ! -d /mnt/sys ] && mkdir -vp /mnt/sys

# Use bind mounts for dev proc and sys within the target device
mount -o bind /dev /mnt/dev && mount -o bind /proc /mnt/proc && mount -o bind /sys /mnt/sys

# Configure apk package manager
cat <<EOF > /mnt/etc/apk/repositories
#/media/vda1/apks
http://dl-cdn.alpinelinux.org/alpine/edge/main
http://dl-cdn.alpinelinux.org/alpine/edge/community
http://dl-cdn.alpinelinux.org/alpine/edge/testing
EOF
</pre>
== Install Alpine from an Alpine host ==

=== Install Alpine with apk ===
Some of what is going to be installed is up to your choosing. This should be enough to get you going and demonstrate how to target an apk installation.
<pre>apk --root /mnt --arch riscv64 --allow-untrusted --initdb add \
alpine-base alpine-baselayout alpine-conf alpine-keys alpine-release alpine-baselayout-data \
kmod openrc dbus util-linux blkid chrony sysfsutils ssl_client openssh ca-certificates-bundle \
alpine-keys ethtool e2fsprogs e2fsprogs-extra libudev-zero libudev-zero-helper parted grep \
busybox-mdev-openrc procps-ng net-tools coreutils doas sed gawk findutils bash shadow pciutils \
mkinitfs</pre>

=== Setup openrc services ===
<pre>for rc in boot/bootmisc boot/hostname boot/modules boot/sysctl boot/urandom boot/networking \
sysinit/devfs sysinit/hwdrivers sysinit/mdev sysinit/modules \
shutdown/mount-ro shutdown/killprocs \
default/dbus default/networking default/chronyd default/local; do
ln -s /etc/init.d/"${rc##*/}" /mnt/etc/runlevels/"$rc"
done</pre>

=== Setup fstab ===
<pre>cp /mnt/etc/fstab /mnt/etc/fstab.orig
echo $(blkid /dev/sdb2 | sed 's/.*: //;s/ .*//;s/"//g') / \ \ \ \ ext4 rw,relatime 0 1 > /mnt/etc/fstab.new
echo $(blkid /dev/sdb1 | sed 's/.*: //;s/ .*//;s/"//g') /boot ext4 rw,relatime 0 2 >> /mnt/etc/fstab.new
cat /mnt/etc/fstab.orig >> /mnt/etc/fstab.new
cp /mnt/etc/fstab.new /mnt/etc/fstab</pre>

=== Setup networking ===
<pre>[ ! -d /mnt/etc/network ] mkdir -vp /mnt/etc/networking
cat <<EOF > /mnt/etc/network/interfaces
auto lo
iface lo inet loopback

auto eth0
iface eth0 inet dhcp

EOF</pre>

=== Set the root password ===
When the system boots it will require a root password. This differs from Alpine install media but that's not the objective of this guide. This guide is installing a ready system.

<pre>passwd -R /mnt root</pre>

=== Enable login on UART ===
<pre>sed -i 's/^#ttyS0/ttyS0/' /mnt/etc/inittab</pre>

== Install Alpine from an non-Alpine RISC-V Linux host ==

=== Download a minirootfs to run apk within a chroot ===
<pre>cd /var/tmp
wget https://dl-cdn.alpinelinux.org/edge/releases/riscv64/alpine-minirootfs-20260127-riscv64.tar.gz</pre>
Unzip in /mnt
<pre>cd /mnt
tar xfpz /var/tmp/alpine-minirootfs-20260127-riscv64.tar.gz</pre>
{{Note|
If installing from a non-Alpine host, you may want to install the kernel image and modules first. Come back to this part to chroot and run the apk step and finish up with mkinitfs}}
Chroot into /mnt and run <code>apk add</code>
<pre>chroot /mnt /bin/sh
apk --arch riscv64 --allow-untrusted --initdb add \
alpine-base alpine-baselayout alpine-conf alpine-keys alpine-release alpine-baselayout-data \
kmod openrc dbus util-linux blkid chrony sysfsutils ssl_client openssh ca-certificates-bundle \
alpine-keys ethtool e2fsprogs e2fsprogs-extra libudev-zero libudev-zero-helper parted grep \
busybox-mdev-openrc procps-ng net-tools coreutils doas sed gawk findutils bash shadow pciutils \
mkinitfs</pre>

=== Setup openrc services ===
<pre>for rc in boot/bootmisc boot/hostname boot/modules boot/sysctl boot/urandom boot/networking \
sysinit/devfs sysinit/hwdrivers sysinit/mdev sysinit/modules \
shutdown/mount-ro shutdown/killprocs \
default/dbus default/networking default/chronyd default/local; do
ln -s /etc/init.d/"${rc##*/}" /etc/runlevels/"$rc"
done</pre>

=== Setup fstab within the chroot ===
<pre>cp /etc/fstab /etc/fstab.orig
echo $(blkid /dev/sdb2 | sed 's/.*: //;s/ .*//;s/"//g') / \ \ \ \ ext4 rw,relatime 0 1 > /etc/fstab.new
echo $(blkid /dev/sdb1 | sed 's/.*: //;s/ .*//;s/"//g') /boot ext4 rw,relatime 0 2 >> /etc/fstab.new
cat /etc/fstab.orig >> /etc/fstab.new
cp /etc/fstab.new /etc/fstab</pre>

=== Setup networking ===
<pre>[ ! -d /etc/network ] mkdir -vp /etc/networking
cat <<EOF > /etc/network/interfaces
auto lo
iface lo inet loopback

auto eth0
iface eth0 inet dhcp

EOF</pre>

=== Set the root password ===
When the system boots it will require a root password. This differs from Alpine install media but that's not the objective of this guide. This guide is installing a ready system.

<pre>passwd</pre>

=== Enable login on UART ===
<pre>sed -i 's/^#ttyS0/ttyS0/' /etc/inittab</pre>

== Setting up the boot environment ==
All of the effort up to this point has come down to this. This portion of the guide will assume the kernel being installed is version 6.6.63-ky from the vendor.
=== Install the kernel ===
=== Install the esos.elf firmware ===
=== Creating the initrd image ===
==== Configuring and fixing mkinitfs ====
===== Add esos.elf to mkinitfs/features.d/base.files =====
<pre>echo "/lib/firmware/esos.elf" >> /etc/mkinitfs/features.d/base.files</pre>
===== Add the wireless-regdb database files to base.files =====
{{Note|
You may not need this. If you see a kernel message regarding failure to load regulatory.db with error -2, this will resolve it}}
<pre>echo "/lib/firmware/regulatory.*" >> /etc/mkinitfs/features.d/base.files</pre>
===== Add jdb2 to ext4 =====
The ext4 module depends on the jdb2 module for filesystem journaling. The Alpine kernel does not have ext4 or jbd2 as kernel builtins. If you're using the Alpine provided kernel then you'll need this on the initramfs.
<pre>echo "kernel/fs/jbd2" >> /etc/mkinitfs/features.d/ext4.modules</pre>
===== Prevent mkinitfs from deleting needed firmware =====
The mkinitfs script will delete a directory that shouldn't exist. The files assembled from the features.d includes will have already been staged prior to mkinitfs assembling firmware needed by included modules. We need this not to happen and below is the simplest workaround I could pull together.
Make a copy of mkinitfs
<pre>cp /sbin/mkinitfs /sbin/mkinitfs-rv2</pre>
In the initfs_firmware function of <code>/sbin/mkinitfs-rv2</code> you will find the following lines
<pre> rm -rf "$tmpdir"/lib/firmware
mkdir -p "$tmpdir"/lib/firmware</pre>
Change them to be
<pre> #rm -rf "$tmpdir"/lib/firmware
[ ! -d "$tmpdir"/lib/firmware ] && mkdir -p "$tmpdir"/lib/firmware</pre>

==== Using mkinitfs-rv2 to create an initrd image ====
=== Configure extlinux ===

== Basic usability options ==

The above should get your OrangePi RV2 booting Alpine Linux. Below are some additional configurations to help make growing your install a little easier. The following assumes you're still chroot /mnt or have booted the system.

=== Add a local user for yourself with escalation privileges ===

Create a user account for yourself with a secondary group of wheel
<pre># Create your account
useradd -G wheel -s /bin/bash -d /home/myuser -m -c "My User" myuser
# Set your password
passwd myuser</pre>

Add a configuration to doas.d for group wheel
<pre>echo permit persist :wheel > /etc/doas.d/00-wheel.conf</pre>

=== Install Avahi for mdns broadcasts ===

Avahi can broadcast names for services provided by your host. The default config in the Alpine package provides a configuration for sshd.

<pre># First setup the hostname
setup-hostname myhost

# Set the hostname
hostname `cat /etc/hostname`

# Install the avahi apk
apk add avahi

# Enable and start the avahi daemon
rc-update add avahi-daemon && rc-service avahi-daemon start</pre>

[[Category:Riscv64]]

Installing Alpine Linux on OrangePi RV2

2026-04-10T03:52:59Z

Aarch0x40:

{{Draft}}
[[Main Page]] > [[:Category:Architectures|Architectures]] > [[Riscv64]] > Installing Alpine Linux on OrangePi RV2
 
{{Warning|The contributors to the Alpine Linux project are not responsible for any damage/loss experienced by using the following guide. This article is provided as a general reference. It is assumed that the implementer will have the knowledge and ability to close the gap between what is described here and their specific setup.}}

The [http://www.orangepi.org/html/hardWare/computerAndMicrocontrollers/details/Orange-Pi-RV2.html OrangePi RV2] is a credit-card sized development board with a Ky X1 8-Core SoC. The Ky X1 is for all intents and purposes a SpacemiT K1 SoC. The remainder of this guide is more likely to use the terms SpacemiT or K1 as is prevalent throughout the Linux community. Please understand that these terms all refer to the same RISC-V ISA implementation.

This guide assumes that the manufacturer provided [https://github.com/riscv-software-src/opensbi OpenSBI] and [https://u-boot.org/ U-Boot] binaries have been applied to the SPI Flash device. This stock bootloader will look for an <code>extlinux/extlinux.conf</code> which will be used to configure the boot process.

Those following this guide may find it useful to have a USB UART serial cable available to debug kernel loading.

This guide borrows heavily from the article [https://arvanta.net/alpine/install-alpine-riscv64-qemu-uboot/ install Alpine Linux riscv64 under qemu with u-boot loader] by Milan P. Stanić and posted to [[Riscv64]] by [[User:AnIDFB]].

== Known issues ==
 
{{Warning|The following are the issues that are known to exist between the result of this guide and the manufacturer provided image}}

* Wireless (Wi-Fi & Bluetooth) is not functional
* Some kernel sources have an issue with starting the framebuffer
* Manufacturer tools are not included

This guide was assembled as a dumping of my personal notes. It's being updated as I come across new information. Alpine does run on the RV2 albeit not directly out of the box. Will do my best to reference external materials so that this article may provide some insight to others while still under development. The above may not be the only issues but hopefully there's enough information here to get you going.

== Kernel and Firmware ==
There are a few different options for kernels. The extent of coverage documented here is largely due to my initial ignorance. I have found a few sources for mostly workable kernels. None of them works 100%. SpacemiT is still in the process upstreaming functionality.

=== Obtaining the ESOS firmware ===
The processor being used on the RV2 requires a firmware to function properly. This file is available from the vendor images, in third party distributions and in the [https://github.com/orangepi-xunlong/orangepi-build orangepi-xunlong/orangepi-build] GitHub repository. The subdirectory containing the required file is [https://github.com/orangepi-xunlong/orangepi-build/tree/next/external/packages/bsp/ky/usr/lib/firmware external/packages/bsp/ky/usr/lib/firmware]. Download the file <code>esos.elf</code>. Keep the download in a safe place and also <code>/lib/firmware</code>. The <code>/lib/firmware</code> directory is also where you'll find this file within the vendor's image or an initrd image.
{{Note|
Changes to mkinitfs will be needed in order for this firmware to be included. More information on that will be provided further down the document}}
=== Obtaining the Vendor kernel ===
Open a browser to the [http://www.orangepi.org/html/hardWare/computerAndMicrocontrollers/service-and-support/Orange-Pi-RV2.html OrangePI RV2 Download] page.

Click on the "Downloads" button for the Ubuntu Image. This will take you to a Google Drive folder. Download the Orangepirv2_1.0.0_ubuntu_noble_server_linux6.6.63.7z.

Decompress this file after downloading using your favorite archive utility. It will expand to a directory containing Orangepirv2_1.0.0_ubuntu_noble_server_linux6.6.63.img and shasum file.

Attach the image to a loop device and mount the root partition.
<pre># Find the first available loop device
doas losetup --find

# Assuming the first found available device is /dev/loop0
doas losetup -P /dev/loop0 Orangepirv2_1.0.0_ubuntu_noble_server_linux6.6.63.img

# Mount the root slice
doas mount /dev/loop0p1 /mnt
</pre>

Archive the vendor kernel
<pre>cd /mnt
tar czf /var/tmp/linux-6.6.63-ky.tgz boot/vmlinuz-6.6.63-ky boot/System.map-6.6.63-ky boot/config-6.6.63-ky boot/dtb-6.6.63-ky lib/modules/6.6.63-ky</pre>
{{Note|
You probably want to put the resulting archive in a safer place than /var/tmp at this point. There's a bit to do before we'll need it.}}

Unmount and detach the vendor image
<pre>cd -
doas umount /mnt
doas losetup -d /dev/loop0</pre>
=== Will Alpine's kernel work? (TBD) ===
{{Note|
Need to revisit this}}
=== Building from source ===
There have been 2 main repositories for patched kernel sources.

* [https://github.com/jasonmontleon/linux-spacemit jasonmontleon/linux-spacemit]
* [https://github.com/BredOS/linux-bredos BredOS/linux-bredos]

The linux-spacemit repository is used by RedHat employee Jason Montleon in building out their RISCV64 support. The linux-bredos repository is used by the BredOS project which supports the RV2 and has provides downloadable images for the board. There is cross contribution between these two repositories. A lot of what I've learned to assemble this guide is attributed to these projects.

==== Setting up a workspace ====

Begin by setting up a RISC-V workspace by following [[Riscv64|Running Alpine riscv64 in QEMU]]. You'll need to establish a build environment in this QEMU guest.

<pre>doas apk add alpine-sdk bison flex openssl-dev ncurses ncurses-dev</pre>

{{Note|
<code>ncurses</code> and <code>ncurses-dev</code> aren't a hard requirements but are useful if you want to run <code>make menuconfig</code>}}

==== Cloning the source, configuring and building the kernel ====

{{Note|
This is needs a redo.}}

== Preparing the media ==

=== Partition and setup the filesystems ===
==== Install parted package ====
<pre>doas apk add parted</pre>
==== Insert, partition and format the boot media ====

The media can be either an SD card or USB drive. An 2280 PCIe NVMe is also possibly if you have the ability to write it from the host setting up the media. For the purposes of this guide we will refer to our boot media as <code>/dev/sdb</code>. The following section requires a root shell.

<pre>alias p="parted -sa optimal /dev/sdb"
p mklabel gpt
p mkpart boot ext4 0G 512M
p set 1 boot
p mkpart root ext4 512M 100%
p p</pre>

The final command should produce output to confirm the result of the executed commands. It should look something like the following.

<pre>Model: Generic STORAGE DEVICE (scsi)
Disk /dev/sdb: 15.5GB
Sector size (logical/physical): 512B/512B
Partition Table: gpt
Disk Flags:

Number Start End Size File system Name Flags
1 1049kB 512MB 511MB ext4 boot boot, esp
2 512MB 15.5GB 15.0GB root
</pre>

If all looks good, then we can proceed with formatting the partitions

<pre>mkfs.ext4 /dev/sdb1 && mkfs.ext4 /dev/sdb2</pre>

Mount the filesystems and lay some preliminary groundwork.

<pre># Mount the target root slice
mount /dev/sdb2 /mnt

# Create mount point for boot slice
[ ! -d /mnt/boot ] && mkdir -vp /mnt/boot

# Mount boot slice
mount /dev/sdb1 /mnt/boot

# Create directory for extlinux config
[ ! -d /mnt/boot/extlinux ] && mkdir -vp /mnt/boot/extlinux

# Create directory for apk config
[ ! -d /mnt/etc/apk ] && mkdir -vp /mnt/etc/apk

# Create mount point for devfs
[ ! -d /mnt/dev ] && mkdir -vp /mnt/dev

# Create mount point for procfs
[ ! -d /mnt/proc ] && mkdir -vp /mnt/proc

# Create mount point for sysfs
[ ! -d /mnt/sys ] && mkdir -vp /mnt/sys

# Use bind mounts for dev proc and sys within the target device
mount -o bind /dev /mnt/dev && mount -o bind /proc /mnt/proc && mount -o bind /sys /mnt/sys

# Configure apk package manager
cat <<EOF > /mnt/etc/apk/repositories
#/media/vda1/apks
http://dl-cdn.alpinelinux.org/alpine/edge/main
http://dl-cdn.alpinelinux.org/alpine/edge/community
http://dl-cdn.alpinelinux.org/alpine/edge/testing
EOF
</pre>
== Install Alpine from an Alpine host ==

=== Install Alpine with apk ===
Some of what is going to be installed is up to your choosing. This should be enough to get you going and demonstrate how to target an apk installation.
<pre>apk --root /mnt --arch riscv64 --allow-untrusted --initdb add \
alpine-base alpine-baselayout alpine-conf alpine-keys alpine-release alpine-baselayout-data \
kmod openrc dbus util-linux blkid chrony sysfsutils ssl_client openssh ca-certificates-bundle \
alpine-keys ethtool e2fsprogs e2fsprogs-extra libudev-zero libudev-zero-helper parted grep \
busybox-mdev-openrc procps-ng net-tools coreutils doas sed gawk findutils bash shadow pciutils \
mkinitfs</pre>

=== Setup openrc services ===
<pre>for rc in boot/bootmisc boot/hostname boot/modules boot/sysctl boot/urandom boot/networking \
sysinit/devfs sysinit/hwdrivers sysinit/mdev sysinit/modules \
shutdown/mount-ro shutdown/killprocs \
default/dbus default/networking default/chronyd default/local; do
ln -s /etc/init.d/"${rc##*/}" /mnt/etc/runlevels/"$rc"
done</pre>

=== Setup fstab ===
<pre>cp /mnt/etc/fstab /mnt/etc/fstab.orig
echo $(blkid /dev/sdb2 | sed 's/.*: //;s/ .*//;s/"//g') / \ \ \ \ ext4 rw,relatime 0 1 > /mnt/etc/fstab.new
echo $(blkid /dev/sdb1 | sed 's/.*: //;s/ .*//;s/"//g') /boot ext4 rw,relatime 0 2 >> /mnt/etc/fstab.new
cat /mnt/etc/fstab.orig >> /mnt/etc/fstab.new
cp /mnt/etc/fstab.new /mnt/etc/fstab</pre>

=== Setup networking ===
<pre>[ ! -d /mnt/etc/network ] mkdir -vp /mnt/etc/networking
cat <<EOF > /mnt/etc/network/interfaces
auto lo
iface lo inet loopback

auto eth0
iface eth0 inet dhcp

EOF</pre>

=== Set the root password ===
When the system boots it will require a root password. This differs from Alpine install media but that's not the objective of this guide. This guide is installing a ready system.

<pre>passwd -R /mnt root</pre>

=== Enable login on UART ===
<pre>sed -i 's/^#ttyS0/ttyS0/' /mnt/etc/inittab</pre>

== Install Alpine from an non-Alpine RISC-V Linux host ==

=== Download a minirootfs to run apk within a chroot ===
<pre>cd /var/tmp
wget https://dl-cdn.alpinelinux.org/edge/releases/riscv64/alpine-minirootfs-20260127-riscv64.tar.gz</pre>
Unzip in /mnt
<pre>cd /mnt
tar xfpz /var/tmp/alpine-minirootfs-20260127-riscv64.tar.gz</pre>
{{Note|
If installing from a non-Alpine host, you may want to install the kernel image and modules first. Come back to this part to chroot and run the apk step and finish up with mkinitfs}}
Chroot into /mnt and run <code>apk add</code>
<pre>chroot /mnt /bin/sh
apk --arch riscv64 --allow-untrusted --initdb add \
alpine-base alpine-baselayout alpine-conf alpine-keys alpine-release alpine-baselayout-data \
kmod openrc dbus util-linux blkid chrony sysfsutils ssl_client openssh ca-certificates-bundle \
alpine-keys ethtool e2fsprogs e2fsprogs-extra libudev-zero libudev-zero-helper parted grep \
busybox-mdev-openrc procps-ng net-tools coreutils doas sed gawk findutils bash shadow pciutils \
mkinitfs</pre>

=== Setup openrc services ===
<pre>for rc in boot/bootmisc boot/hostname boot/modules boot/sysctl boot/urandom boot/networking \
sysinit/devfs sysinit/hwdrivers sysinit/mdev sysinit/modules \
shutdown/mount-ro shutdown/killprocs \
default/dbus default/networking default/chronyd default/local; do
ln -s /etc/init.d/"${rc##*/}" /etc/runlevels/"$rc"
done</pre>

=== Setup fstab within the chroot ===
<pre>cp /etc/fstab /etc/fstab.orig
echo $(blkid /dev/sdb2 | sed 's/.*: //;s/ .*//;s/"//g') / \ \ \ \ ext4 rw,relatime 0 1 > /etc/fstab.new
echo $(blkid /dev/sdb1 | sed 's/.*: //;s/ .*//;s/"//g') /boot ext4 rw,relatime 0 2 >> /etc/fstab.new
cat /etc/fstab.orig >> /etc/fstab.new
cp /etc/fstab.new /etc/fstab</pre>

=== Setup networking ===
<pre>[ ! -d /etc/network ] mkdir -vp /etc/networking
cat <<EOF > /etc/network/interfaces
auto lo
iface lo inet loopback

auto eth0
iface eth0 inet dhcp

EOF</pre>

=== Set the root password ===
When the system boots it will require a root password. This differs from Alpine install media but that's not the objective of this guide. This guide is installing a ready system.

<pre>passwd</pre>

=== Enable login on UART ===
<pre>sed -i 's/^#ttyS0/ttyS0/' /etc/inittab</pre>

== Setting up the boot environment ==
All of the effort up to this point has come down to this. This portion of the guide will assume the kernel being installed is version 6.6.63-ky from the vendor.
=== Install the kernel ===
=== Install the esos.elf firmware ===
=== Creating the initrd image ===
==== Configuring and fixing mkinitfs ====
===== Add esos.elf to mkinitfs/features.d/base.files =====
<pre>echo "/lib/firmware/esos.elf" >> /etc/mkinitfs/features.d/base.files</pre>
===== Add the wireless-regdb database files to base.files =====
{{Note|
You may not need this. If you see a kernel message regarding failure to load regulatory.db with error -2, this will resolve it}}
<pre>echo "/lib/firmware/regulatory.*" >> /etc/mkinitfs/features.d/base.files</pre>
===== Add jdb2 to ext4 =====
The ext4 module depends on the jdb2 module for filesystem journaling. The Alpine kernel does not have ext4 or jbd2 as kernel builtins. If you're using the Alpine provided kernel then you'll need this on the initramfs.
<pre>echo "kernel/fs/jbd2" >> /etc/mkinitfs/features.d/ext4.modules</pre>
===== Prevent mkinitfs from deleting needed firmware =====
The mkinitfs script will delete a directory that shouldn't exist. The files assembled from the features.d includes will have already been staged prior to mkinitfs assembling firmware needed by included modules. We need this not to happen and below is the simplest workaround I could pull together.
Make a copy of mkinitfs
<pre>cp /sbin/mkinitfs /sbin/mkinitfs-rv2</pre>
In the initfs_firmware function of <code>/sbin/mkinitfs-rv2</code> you will find the following lines
<pre> rm -rf "$tmpdir"/lib/firmware
mkdir -p "$tmpdir"/lib/firmware</pre>
Change them to be
<pre> #rm -rf "$tmpdir"/lib/firmware
[ ! -d "$tmpdir"/lib/firmware ] && mkdir -p "$tmpdir"/lib/firmware</pre>

==== Using mkinitfs-rv2 to create an initrd image ====
=== Configure extlinux ===

== Basic usability options ==

The above should get your OrangePi RV2 booting Alpine Linux. Below are some additional configurations to help make growing your install a little easier. The following assumes you're still chroot /mnt or have booted the system.

=== Add a local user for yourself with escalation privileges ===

Create a user account for yourself with a secondary group of wheel
<pre># Create your account
useradd -G wheel -s /bin/bash -d /home/myuser -m -c "My User" myuser
# Set your password
passwd myuser</pre>

Add a configuration to doas.d for group wheel
<pre>echo permit persist :wheel > /etc/doas.d/00-wheel.conf</pre>

=== Install Avahi for mdns broadcasts ===

Avahi can broadcast names for services provided by your host. The default config in the Alpine package provides a configuration for sshd.

<pre># First setup the hostname
setup-hostname myhost

# Set the hostname
hostname `cat /etc/hostname`

# Install the avahi apk
apk add avahi

# Enable and start the avahi daemon
rc-update add avahi-daemon && rc-service avahi-daemon start</pre>

[[Category:Riscv64]]

Installing Alpine Linux on OrangePi RV2

2026-04-10T03:48:54Z

Aarch0x40:

{{Draft}}
[[Main Page]] > [[:Category:Architectures|Architectures]] > [[Riscv64]] > Installing Alpine Linux on OrangePi RV2
 
{{Warning|The contributors to the Alpine Linux project are not responsible for any damage/loss experienced by using the following guide. This article is provided as a general reference. It is assumed that the implementer will have the knowledge and ability to close the gap between what is described here and their specific setup.}}

The [http://www.orangepi.org/html/hardWare/computerAndMicrocontrollers/details/Orange-Pi-RV2.html OrangePi RV2] is a credit-card sized development board with a Ky X1 8-Core SoC. The Ky X1 is for all intents and purposes a SpacemiT K1 SoC. The remainder of this guide is more likely to use the terms SpacemiT or K1 as is prevalent throughout the Linux community. Please understand that these terms all refer to the same RISC-V ISA implementation.

This guide assumes that the manufacturer provided [https://github.com/riscv-software-src/opensbi OpenSBI] and [https://u-boot.org/ U-Boot] binaries have been applied to the SPI Flash device. This stock bootloader will look for an <code>extlinux/extlinux.conf</code> which will be used to configure the boot process.

Those following this guide may find it useful to have a USB UART serial cable available to debug kernel loading.

This guide borrows heavily from the article [https://arvanta.net/alpine/install-alpine-riscv64-qemu-uboot/ install Alpine Linux riscv64 under qemu with u-boot loader] by Milan P. Stanić and posted to [[Riscv64]] by [[User:AnIDFB]].

== Known issues ==
 
{{Warning|The following are the issues that are known to exist between the result of this guide and the manufacturer provided image}}

* Wireless (Wi-Fi & Bluetooth) is not functional
* Some kernel sources have an issue with starting the framebuffer
* Manufacturer tools are not included

This guide was assembled as a dumping of my personal notes. It's being updated as I come across new information. Alpine does run on the RV2 albeit not directly out of the box. Will do my best to reference external materials so that this article may provide some insight to others while still under development. The above may not be the only issues but hopefully there's enough information here to get you going.

== Kernel and Firmware ==
There are a few different options for kernels. The extent of coverage documented here is largely due to my initial ignorance. I have found a few sources for mostly workable kernels. None of them works 100%. SpacemiT is still in the process upstreaming functionality.

=== Obtaining the ESOS firmware ===
The processor being used on the RV2 requires a firmware to function properly. This file is available from the vendor images, in third party distributions and in the [https://github.com/orangepi-xunlong/orangepi-build orangepi-xunlong/orangepi-build] GitHub repository. The subdirectory containing the required file is [https://github.com/orangepi-xunlong/orangepi-build/tree/next/external/packages/bsp/ky/usr/lib/firmware external/packages/bsp/ky/usr/lib/firmware]. Download the file <code>esos.elf</code>. Keep the download in a safe place and also <code>/lib/firmware</code>. The <code>/lib/firmware</code> directory is also where you'll find this file within the vendor's image or an initrd image.
{{Note|
Changes to mkinitfs will be needed in order for this firmware to be included. More information on that will be provided further down the document}}
=== Obtaining the Vendor kernel ===
Open a browser to the [http://www.orangepi.org/html/hardWare/computerAndMicrocontrollers/service-and-support/Orange-Pi-RV2.html OrangePI RV2 Download] page.

Click on the "Downloads" button for the Ubuntu Image. This will take you to a Google Drive folder. Download the Orangepirv2_1.0.0_ubuntu_noble_server_linux6.6.63.7z.

Decompress this file after downloading using your favorite archive utility. It will expand to a directory containing Orangepirv2_1.0.0_ubuntu_noble_server_linux6.6.63.img and shasum file.

Attach the image to a loop device and mount the root partition.
<pre># Find the first available loop device
doas losetup --find

# Assuming the first found available device is /dev/loop0
doas losetup -P /dev/loop0 Orangepirv2_1.0.0_ubuntu_noble_server_linux6.6.63.img

# Mount the root slice
doas mount /dev/loop0p1 /mnt
</pre>

Archive the vendor kernel
<pre>cd /mnt
tar czf /var/tmp/linux-6.6.63-ky.tgz boot/vmlinuz-6.6.63-ky boot/System.map-6.6.63-ky boot/config-6.6.63-ky boot/dtb-6.6.63-ky lib/modules/6.6.63-ky</pre>
{{Note|
You probably want to put the resulting archive in a safer place than /var/tmp at this point. There's a bit to do before we'll need it.}}

Unmount and detach the vendor image
<pre>cd -
doas umount /mnt
doas losetup -d /dev/loop0</pre>
=== Will Alpine's kernel work? (TBD) ===
{{Note|
Need to revisit this}}
=== Building from source ===
There have been 2 main repositories for patched kernel sources.

* [https://github.com/jasonmontleon/linux-spacemit jasonmontleon/linux-spacemit]
* [https://github.com/BredOS/linux-bredos BredOS/linux-bredos]

The linux-spacemit repository is used by RedHat employee Jason Montleon in building out their RISCV64 support. The linux-bredos repository is used by the BredOS project which supports the RV2 and has provides downloadable images for the board. There is cross contribution between these two repositories. A lot of what I've learned to assemble this guide is attributed to these projects.

==== Setting up a workspace ====

Begin by setting up a RISC-V workspace by following [[Riscv64|Running Alpine riscv64 in QEMU]]. You'll need to establish a build environment in this QEMU guest.

<pre>doas apk add alpine-sdk bison flex openssl-dev ncurses ncurses-dev</pre>

{{Note|
<code>ncurses</code> and <code>ncurses-dev</code> aren't a hard requirements but are useful if you want to run <code>make menuconfig</code>}}

==== Cloning the source, configuring and building the kernel ====

Unfortunately the stock kernels provided by the Alpine Linux project and even the source tarballs from kernel.org will not work. There's still a bit of patchwork involved as not all support is up-streamed. Fortunately there is someone who is maintaining repository with patched kernel sources. These sources are current to 6.18.20.

The following command will clone just the current HEAD of the patched repository

<pre>git clone --depth 1 https://github.com/jasonmontleon/linux-spacemit.git
cd linux-spacemit
make ARCH=riscv k1_defconfig
make -j$(nproc)</pre>

{{Note|
The kernel build may fail. I recommend starting with the k1_defconfig and working through errors as they come up. Only the RealTek 8852BS was an issue at the time of this writing.}}

== Preparing the media ==

=== Partition and setup the filesystems ===
==== Install parted package ====
<pre>doas apk add parted</pre>
==== Insert, partition and format the boot media ====

The media can be either an SD card or USB drive. An 2280 PCIe NVMe is also possibly if you have the ability to write it from the host setting up the media. For the purposes of this guide we will refer to our boot media as <code>/dev/sdb</code>. The following section requires a root shell.

<pre>alias p="parted -sa optimal /dev/sdb"
p mklabel gpt
p mkpart boot ext4 0G 512M
p set 1 boot
p mkpart root ext4 512M 100%
p p</pre>

The final command should produce output to confirm the result of the executed commands. It should look something like the following.

<pre>Model: Generic STORAGE DEVICE (scsi)
Disk /dev/sdb: 15.5GB
Sector size (logical/physical): 512B/512B
Partition Table: gpt
Disk Flags:

Number Start End Size File system Name Flags
1 1049kB 512MB 511MB ext4 boot boot, esp
2 512MB 15.5GB 15.0GB root
</pre>

If all looks good, then we can proceed with formatting the partitions

<pre>mkfs.ext4 /dev/sdb1 && mkfs.ext4 /dev/sdb2</pre>

Mount the filesystems and lay some preliminary groundwork.

<pre># Mount the target root slice
mount /dev/sdb2 /mnt

# Create mount point for boot slice
[ ! -d /mnt/boot ] && mkdir -vp /mnt/boot

# Mount boot slice
mount /dev/sdb1 /mnt/boot

# Create directory for extlinux config
[ ! -d /mnt/boot/extlinux ] && mkdir -vp /mnt/boot/extlinux

# Create directory for apk config
[ ! -d /mnt/etc/apk ] && mkdir -vp /mnt/etc/apk

# Create mount point for devfs
[ ! -d /mnt/dev ] && mkdir -vp /mnt/dev

# Create mount point for procfs
[ ! -d /mnt/proc ] && mkdir -vp /mnt/proc

# Create mount point for sysfs
[ ! -d /mnt/sys ] && mkdir -vp /mnt/sys

# Use bind mounts for dev proc and sys within the target device
mount -o bind /dev /mnt/dev && mount -o bind /proc /mnt/proc && mount -o bind /sys /mnt/sys

# Configure apk package manager
cat <<EOF > /mnt/etc/apk/repositories
#/media/vda1/apks
http://dl-cdn.alpinelinux.org/alpine/edge/main
http://dl-cdn.alpinelinux.org/alpine/edge/community
http://dl-cdn.alpinelinux.org/alpine/edge/testing
EOF
</pre>
== Install Alpine from an Alpine host ==

=== Install Alpine with apk ===
Some of what is going to be installed is up to your choosing. This should be enough to get you going and demonstrate how to target an apk installation.
<pre>apk --root /mnt --arch riscv64 --allow-untrusted --initdb add \
alpine-base alpine-baselayout alpine-conf alpine-keys alpine-release alpine-baselayout-data \
kmod openrc dbus util-linux blkid chrony sysfsutils ssl_client openssh ca-certificates-bundle \
alpine-keys ethtool e2fsprogs e2fsprogs-extra libudev-zero libudev-zero-helper parted grep \
busybox-mdev-openrc procps-ng net-tools coreutils doas sed gawk findutils bash shadow pciutils \
mkinitfs</pre>

=== Setup openrc services ===
<pre>for rc in boot/bootmisc boot/hostname boot/modules boot/sysctl boot/urandom boot/networking \
sysinit/devfs sysinit/hwdrivers sysinit/mdev sysinit/modules \
shutdown/mount-ro shutdown/killprocs \
default/dbus default/networking default/chronyd default/local; do
ln -s /etc/init.d/"${rc##*/}" /mnt/etc/runlevels/"$rc"
done</pre>

=== Setup fstab ===
<pre>cp /mnt/etc/fstab /mnt/etc/fstab.orig
echo $(blkid /dev/sdb2 | sed 's/.*: //;s/ .*//;s/"//g') / \ \ \ \ ext4 rw,relatime 0 1 > /mnt/etc/fstab.new
echo $(blkid /dev/sdb1 | sed 's/.*: //;s/ .*//;s/"//g') /boot ext4 rw,relatime 0 2 >> /mnt/etc/fstab.new
cat /mnt/etc/fstab.orig >> /mnt/etc/fstab.new
cp /mnt/etc/fstab.new /mnt/etc/fstab</pre>

=== Setup networking ===
<pre>[ ! -d /mnt/etc/network ] mkdir -vp /mnt/etc/networking
cat <<EOF > /mnt/etc/network/interfaces
auto lo
iface lo inet loopback

auto eth0
iface eth0 inet dhcp

EOF</pre>

=== Set the root password ===
When the system boots it will require a root password. This differs from Alpine install media but that's not the objective of this guide. This guide is installing a ready system.

<pre>passwd -R /mnt root</pre>

=== Enable login on UART ===
<pre>sed -i 's/^#ttyS0/ttyS0/' /mnt/etc/inittab</pre>

== Install Alpine from an non-Alpine RISC-V Linux host ==

=== Download a minirootfs to run apk within a chroot ===
<pre>cd /var/tmp
wget https://dl-cdn.alpinelinux.org/edge/releases/riscv64/alpine-minirootfs-20260127-riscv64.tar.gz</pre>
Unzip in /mnt
<pre>cd /mnt
tar xfpz /var/tmp/alpine-minirootfs-20260127-riscv64.tar.gz</pre>
{{Note|
If installing from a non-Alpine host, you may want to install the kernel image and modules first. Come back to this part to chroot and run the apk step and finish up with mkinitfs}}
Chroot into /mnt and run <code>apk add</code>
<pre>chroot /mnt /bin/sh
apk --arch riscv64 --allow-untrusted --initdb add \
alpine-base alpine-baselayout alpine-conf alpine-keys alpine-release alpine-baselayout-data \
kmod openrc dbus util-linux blkid chrony sysfsutils ssl_client openssh ca-certificates-bundle \
alpine-keys ethtool e2fsprogs e2fsprogs-extra libudev-zero libudev-zero-helper parted grep \
busybox-mdev-openrc procps-ng net-tools coreutils doas sed gawk findutils bash shadow pciutils \
mkinitfs</pre>

=== Setup openrc services ===
<pre>for rc in boot/bootmisc boot/hostname boot/modules boot/sysctl boot/urandom boot/networking \
sysinit/devfs sysinit/hwdrivers sysinit/mdev sysinit/modules \
shutdown/mount-ro shutdown/killprocs \
default/dbus default/networking default/chronyd default/local; do
ln -s /etc/init.d/"${rc##*/}" /etc/runlevels/"$rc"
done</pre>

=== Setup fstab within the chroot ===
<pre>cp /etc/fstab /etc/fstab.orig
echo $(blkid /dev/sdb2 | sed 's/.*: //;s/ .*//;s/"//g') / \ \ \ \ ext4 rw,relatime 0 1 > /etc/fstab.new
echo $(blkid /dev/sdb1 | sed 's/.*: //;s/ .*//;s/"//g') /boot ext4 rw,relatime 0 2 >> /etc/fstab.new
cat /etc/fstab.orig >> /etc/fstab.new
cp /etc/fstab.new /etc/fstab</pre>

=== Setup networking ===
<pre>[ ! -d /etc/network ] mkdir -vp /etc/networking
cat <<EOF > /etc/network/interfaces
auto lo
iface lo inet loopback

auto eth0
iface eth0 inet dhcp

EOF</pre>

=== Set the root password ===
When the system boots it will require a root password. This differs from Alpine install media but that's not the objective of this guide. This guide is installing a ready system.

<pre>passwd</pre>

=== Enable login on UART ===
<pre>sed -i 's/^#ttyS0/ttyS0/' /etc/inittab</pre>

== Setting up the boot environment ==
All of the effort up to this point has come down to this. This portion of the guide will assume the kernel being installed is version 6.6.63-ky from the vendor.
=== Install the kernel ===
=== Install the esos.elf firmware ===
=== Creating the initrd image ===
==== Configuring and fixing mkinitfs ====
===== Add esos.elf to mkinitfs/features.d/base.files =====
<pre>echo "/lib/firmware/esos.elf" >> /etc/mkinitfs/features.d/base.files</pre>
===== Add the wireless-regdb database files to base.files =====
{{Note|
You may not need this. If you see a kernel message regarding failure to load regulatory.db with error -2, this will resolve it}}
<pre>echo "/lib/firmware/regulatory.*" >> /etc/mkinitfs/features.d/base.files</pre>
===== Add jdb2 to ext4 =====
The ext4 module depends on the jdb2 module for filesystem journaling. The Alpine kernel does not have ext4 or jbd2 as kernel builtins. If you're using the Alpine provided kernel then you'll need this on the initramfs.
<pre>echo "kernel/fs/jbd2" >> /etc/mkinitfs/features.d/ext4.modules</pre>
===== Prevent mkinitfs from deleting needed firmware =====
The mkinitfs script will delete a directory that shouldn't exist. The files assembled from the features.d includes will have already been staged prior to mkinitfs assembling firmware needed by included modules. We need this not to happen and below is the simplest workaround I could pull together.
Make a copy of mkinitfs
<pre>cp /sbin/mkinitfs /sbin/mkinitfs-rv2</pre>
In the initfs_firmware function of <code>/sbin/mkinitfs-rv2</code> you will find the following lines
<pre> rm -rf "$tmpdir"/lib/firmware
mkdir -p "$tmpdir"/lib/firmware</pre>
Change them to be
<pre> #rm -rf "$tmpdir"/lib/firmware
[ ! -d "$tmpdir"/lib/firmware ] && mkdir -p "$tmpdir"/lib/firmware</pre>

==== Using mkinitfs-rv2 to create an initrd image ====
=== Configure extlinux ===

== Basic usability options ==

The above should get your OrangePi RV2 booting Alpine Linux. Below are some additional configurations to help make growing your install a little easier. The following assumes you're still chroot /mnt or have booted the system.

=== Add a local user for yourself with escalation privileges ===

Create a user account for yourself with a secondary group of wheel
<pre># Create your account
useradd -G wheel -s /bin/bash -d /home/myuser -m -c "My User" myuser
# Set your password
passwd myuser</pre>

Add a configuration to doas.d for group wheel
<pre>echo permit persist :wheel > /etc/doas.d/00-wheel.conf</pre>

=== Install Avahi for mdns broadcasts ===

Avahi can broadcast names for services provided by your host. The default config in the Alpine package provides a configuration for sshd.

<pre># First setup the hostname
setup-hostname myhost

# Set the hostname
hostname `cat /etc/hostname`

# Install the avahi apk
apk add avahi

# Enable and start the avahi daemon
rc-update add avahi-daemon && rc-service avahi-daemon start</pre>

[[Category:Riscv64]]

Installing Alpine Linux on OrangePi RV2

2026-04-10T03:24:17Z

Aarch0x40:

{{Draft}}
[[Main Page]] > [[:Category:Architectures|Architectures]] > [[Riscv64]] > Installing Alpine Linux on OrangePi RV2
 
{{Warning|The contributors to the Alpine Linux project are not responsible for any damage/loss experienced by using the following guide. This article is provided as a general reference. It is assumed that the implementer will have the knowledge and ability to close the gap between what is described here and their specific setup.}}

The [http://www.orangepi.org/html/hardWare/computerAndMicrocontrollers/details/Orange-Pi-RV2.html OrangePi RV2] is a credit-card sized development board with a Ky X1 8-Core SoC. The Ky X1 is for all intents and purposes a SpacemiT K1 SoC. The remainder of this guide is more likely to use the terms SpacemiT or K1 as is prevalent throughout the Linux community. Please understand that these terms all refer to the same RISC-V ISA implementation.

This guide assumes that the manufacturer provided [https://github.com/riscv-software-src/opensbi OpenSBI] and [https://u-boot.org/ U-Boot] binaries have been applied to the SPI Flash device. This stock bootloader will look for an <code>extlinux/extlinux.conf</code> which will be used to configure the boot process.

Those following this guide may find it useful to have a USB UART serial cable available to debug kernel loading.

This guide borrows heavily from the article [https://arvanta.net/alpine/install-alpine-riscv64-qemu-uboot/ install Alpine Linux riscv64 under qemu with u-boot loader] by Milan P. Stanić and posted to [[Riscv64]] by [[User:AnIDFB]].

== Known issues ==
 
{{Warning|The following are the issues that are known to exist between the result of this guide and the manufacturer provided image}}

* Wireless (Wi-Fi & Bluetooth) is not functional
* Some kernel sources have an issue with starting the framebuffer
* Manufacturer tools are not included

This guide was assembled as a dumping of my personal notes. It's being updated as I come across new information. Alpine does run on the RV2 albeit not directly out of the box. Will do my best to reference external materials so that this article may provide some insight to others while still under development. The above may not be the only issues but hopefully there's enough information here to get you going.

== Kernel and Firmware ==
There are a few different options for kernels. The extent of coverage documented here is largely due to my initial ignorance. I have found a few sources for mostly workable kernels. None of them works 100%. SpacemiT is still in the process upstreaming functionality.

=== Obtaining the ESOS firmware ===
The processor being used on the RV2 requires a firmware to function properly. This file is available from the vendor images, in third party distributions and in the [https://github.com/orangepi-xunlong/orangepi-build orangepi-xunlong/orangepi-build] GitHub repository. The subdirectory containing the required file is [https://github.com/orangepi-xunlong/orangepi-build/tree/next/external/packages/bsp/ky/usr/lib/firmware external/packages/bsp/ky/usr/lib/firmware]. Download the file <code>esos.elf</code>. Keep the download in a safe place and also <code>/lib/firmware</code>. The <code>/lib/firmware</code> directory is also where you'll find this file within the vendor's image or an initrd image.
{{Note|
Changes to mkinitfs will be needed in order for this firmware to be included. More information on that will be provided further down the document}}
=== Obtaining the Vendor kernel ===
Open a browser to the [http://www.orangepi.org/html/hardWare/computerAndMicrocontrollers/service-and-support/Orange-Pi-RV2.html OrangePI RV2 Download] page.
=== Will Alpine's kernel work? (TBD) ===
{{Note|
Need to revisit this}}
=== Building from source ===
There have been 2 main repositories for patched kernel sources.

* [https://github.com/jasonmontleon/linux-spacemit jasonmontleon/linux-spacemit]
* [https://github.com/BredOS/linux-bredos BredOS/linux-bredos]

The linux-spacemit repository is used by RedHat employee Jason Montleon in building out their RISCV64 support. The linux-bredos repository is used by the BredOS project which supports the RV2 and has provides downloadable images for the board. There is cross contribution between these two repositories. A lot of what I've learned to assemble this guide is attributed to these projects.

==== Setting up a workspace ====

Begin by setting up a RISC-V workspace by following [[Riscv64|Running Alpine riscv64 in QEMU]]. You'll need to establish a build environment in this QEMU guest.

<pre>doas apk add alpine-sdk bison flex openssl-dev ncurses ncurses-dev</pre>

{{Note|
<code>ncurses</code> and <code>ncurses-dev</code> aren't a hard requirements but are useful if you want to run <code>make menuconfig</code>}}

==== Cloning the source, configuring and building the kernel ====

Unfortunately the stock kernels provided by the Alpine Linux project and even the source tarballs from kernel.org will not work. There's still a bit of patchwork involved as not all support is up-streamed. Fortunately there is someone who is maintaining repository with patched kernel sources. These sources are current to 6.18.20.

The following command will clone just the current HEAD of the patched repository

<pre>git clone --depth 1 https://github.com/jasonmontleon/linux-spacemit.git
cd linux-spacemit
make ARCH=riscv k1_defconfig
make -j$(nproc)</pre>

{{Note|
The kernel build may fail. I recommend starting with the k1_defconfig and working through errors as they come up. Only the RealTek 8852BS was an issue at the time of this writing.}}

== Preparing the media ==

=== Partition and setup the filesystems ===
==== Install parted package ====
<pre>doas apk add parted</pre>
==== Insert, partition and format the boot media ====

The media can be either an SD card or USB drive. An 2280 PCIe NVMe is also possibly if you have the ability to write it from the host setting up the media. For the purposes of this guide we will refer to our boot media as <code>/dev/sdb</code>. The following section requires a root shell.

<pre>alias p="parted -sa optimal /dev/sdb"
p mklabel gpt
p mkpart boot ext4 0G 512M
p set 1 boot
p mkpart root ext4 512M 100%
p p</pre>

The final command should produce output to confirm the result of the executed commands. It should look something like the following.

<pre>Model: Generic STORAGE DEVICE (scsi)
Disk /dev/sdb: 15.5GB
Sector size (logical/physical): 512B/512B
Partition Table: gpt
Disk Flags:

Number Start End Size File system Name Flags
1 1049kB 512MB 511MB ext4 boot boot, esp
2 512MB 15.5GB 15.0GB root
</pre>

If all looks good, then we can proceed with formatting the partitions

<pre>mkfs.ext4 /dev/sdb1 && mkfs.ext4 /dev/sdb2</pre>

Mount the filesystems and lay some preliminary groundwork.

<pre># Mount the target root slice
mount /dev/sdb2 /mnt

# Create mount point for boot slice
[ ! -d /mnt/boot ] && mkdir -vp /mnt/boot

# Mount boot slice
mount /dev/sdb1 /mnt/boot

# Create directory for extlinux config
[ ! -d /mnt/boot/extlinux ] && mkdir -vp /mnt/boot/extlinux

# Create directory for apk config
[ ! -d /mnt/etc/apk ] && mkdir -vp /mnt/etc/apk

# Create mount point for devfs
[ ! -d /mnt/dev ] && mkdir -vp /mnt/dev

# Create mount point for procfs
[ ! -d /mnt/proc ] && mkdir -vp /mnt/proc

# Create mount point for sysfs
[ ! -d /mnt/sys ] && mkdir -vp /mnt/sys

# Use bind mounts for dev proc and sys within the target device
mount -o bind /dev /mnt/dev && mount -o bind /proc /mnt/proc && mount -o bind /sys /mnt/sys

# Configure apk package manager
cat <<EOF > /mnt/etc/apk/repositories
#/media/vda1/apks
http://dl-cdn.alpinelinux.org/alpine/edge/main
http://dl-cdn.alpinelinux.org/alpine/edge/community
http://dl-cdn.alpinelinux.org/alpine/edge/testing
EOF
</pre>
== Install Alpine from an Alpine host ==

=== Install Alpine with apk ===
Some of what is going to be installed is up to your choosing. This should be enough to get you going and demonstrate how to target an apk installation.
<pre>apk --root /mnt --arch riscv64 --allow-untrusted --initdb add \
alpine-base alpine-baselayout alpine-conf alpine-keys alpine-release alpine-baselayout-data \
kmod openrc dbus util-linux blkid chrony sysfsutils ssl_client openssh ca-certificates-bundle \
alpine-keys ethtool e2fsprogs e2fsprogs-extra libudev-zero libudev-zero-helper parted grep \
busybox-mdev-openrc procps-ng net-tools coreutils doas sed gawk findutils bash shadow pciutils \
mkinitfs</pre>

=== Setup openrc services ===
<pre>for rc in boot/bootmisc boot/hostname boot/modules boot/sysctl boot/urandom boot/networking \
sysinit/devfs sysinit/hwdrivers sysinit/mdev sysinit/modules \
shutdown/mount-ro shutdown/killprocs \
default/dbus default/networking default/chronyd default/local; do
ln -s /etc/init.d/"${rc##*/}" /mnt/etc/runlevels/"$rc"
done</pre>

=== Setup fstab ===
<pre>cp /mnt/etc/fstab /mnt/etc/fstab.orig
echo $(blkid /dev/sdb2 | sed 's/.*: //;s/ .*//;s/"//g') / \ \ \ \ ext4 rw,relatime 0 1 > /mnt/etc/fstab.new
echo $(blkid /dev/sdb1 | sed 's/.*: //;s/ .*//;s/"//g') /boot ext4 rw,relatime 0 2 >> /mnt/etc/fstab.new
cat /mnt/etc/fstab.orig >> /mnt/etc/fstab.new
cp /mnt/etc/fstab.new /mnt/etc/fstab</pre>

=== Setup networking ===
<pre>[ ! -d /mnt/etc/network ] mkdir -vp /mnt/etc/networking
cat <<EOF > /mnt/etc/network/interfaces
auto lo
iface lo inet loopback

auto eth0
iface eth0 inet dhcp

EOF</pre>

=== Set the root password ===
When the system boots it will require a root password. This differs from Alpine install media but that's not the objective of this guide. This guide is installing a ready system.

<pre>passwd -R /mnt root</pre>

=== Enable login on UART ===
<pre>sed -i 's/^#ttyS0/ttyS0/' /mnt/etc/inittab</pre>

== Install Alpine from an non-Alpine RISC-V Linux host ==

=== Download a minirootfs to run apk within a chroot ===
<pre>cd /var/tmp
wget https://dl-cdn.alpinelinux.org/edge/releases/riscv64/alpine-minirootfs-20260127-riscv64.tar.gz</pre>
Unzip in /mnt
<pre>cd /mnt
tar xfpz /var/tmp/alpine-minirootfs-20260127-riscv64.tar.gz</pre>
{{Note|
If installing from a non-Alpine host, you may want to install the kernel image and modules first. Come back to this part to chroot and run the apk step and finish up with mkinitfs}}
Chroot into /mnt and run <code>apk add</code>
<pre>chroot /mnt /bin/sh
apk --arch riscv64 --allow-untrusted --initdb add \
alpine-base alpine-baselayout alpine-conf alpine-keys alpine-release alpine-baselayout-data \
kmod openrc dbus util-linux blkid chrony sysfsutils ssl_client openssh ca-certificates-bundle \
alpine-keys ethtool e2fsprogs e2fsprogs-extra libudev-zero libudev-zero-helper parted grep \
busybox-mdev-openrc procps-ng net-tools coreutils doas sed gawk findutils bash shadow pciutils \
mkinitfs</pre>

=== Setup openrc services ===
<pre>for rc in boot/bootmisc boot/hostname boot/modules boot/sysctl boot/urandom boot/networking \
sysinit/devfs sysinit/hwdrivers sysinit/mdev sysinit/modules \
shutdown/mount-ro shutdown/killprocs \
default/dbus default/networking default/chronyd default/local; do
ln -s /etc/init.d/"${rc##*/}" /etc/runlevels/"$rc"
done</pre>

=== Setup fstab within the chroot ===
<pre>cp /etc/fstab /etc/fstab.orig
echo $(blkid /dev/sdb2 | sed 's/.*: //;s/ .*//;s/"//g') / \ \ \ \ ext4 rw,relatime 0 1 > /etc/fstab.new
echo $(blkid /dev/sdb1 | sed 's/.*: //;s/ .*//;s/"//g') /boot ext4 rw,relatime 0 2 >> /etc/fstab.new
cat /etc/fstab.orig >> /etc/fstab.new
cp /etc/fstab.new /etc/fstab</pre>

=== Setup networking ===
<pre>[ ! -d /etc/network ] mkdir -vp /etc/networking
cat <<EOF > /etc/network/interfaces
auto lo
iface lo inet loopback

auto eth0
iface eth0 inet dhcp

EOF</pre>

=== Set the root password ===
When the system boots it will require a root password. This differs from Alpine install media but that's not the objective of this guide. This guide is installing a ready system.

<pre>passwd</pre>

=== Enable login on UART ===
<pre>sed -i 's/^#ttyS0/ttyS0/' /etc/inittab</pre>

== Setting up the boot environment ==
All of the effort up to this point has come down to this. This portion of the guide will assume the kernel being installed is version 6.6.63-ky from the vendor.
=== Install the kernel ===
=== Install the esos.elf firmware ===
=== Creating the initrd image ===
==== Configuring and fixing mkinitfs ====
===== Add esos.elf to mkinitfs/features.d/base.files =====
<pre>echo "/lib/firmware/esos.elf" >> /etc/mkinitfs/features.d/base.files</pre>
===== Add the wireless-regdb database files to base.files =====
{{Note|
You may not need this. If you see a kernel message regarding failure to load regulatory.db with error -2, this will resolve it}}
<pre>echo "/lib/firmware/regulatory.*" >> /etc/mkinitfs/features.d/base.files</pre>
===== Add jdb2 to ext4 =====
The ext4 module depends on the jdb2 module for filesystem journaling. The Alpine kernel does not have ext4 or jbd2 as kernel builtins. If you're using the Alpine provided kernel then you'll need this on the initramfs.
<pre>echo "kernel/fs/jbd2" >> /etc/mkinitfs/features.d/ext4.modules</pre>
===== Prevent mkinitfs from deleting needed firmware =====
The mkinitfs script will delete a directory that shouldn't exist. The files assembled from the features.d includes will have already been staged prior to mkinitfs assembling firmware needed by included modules. We need this not to happen and below is the simplest workaround I could pull together.
Make a copy of mkinitfs
<pre>cp /sbin/mkinitfs /sbin/mkinitfs-rv2</pre>
In the initfs_firmware function of <code>/sbin/mkinitfs-rv2</code> you will find the following lines
<pre> rm -rf "$tmpdir"/lib/firmware
mkdir -p "$tmpdir"/lib/firmware</pre>
Change them to be
<pre> #rm -rf "$tmpdir"/lib/firmware
[ ! -d "$tmpdir"/lib/firmware ] && mkdir -p "$tmpdir"/lib/firmware</pre>

==== Using mkinitfs-rv2 to create an initrd image ====
=== Configure extlinux ===

== Basic usability options ==

The above should get your OrangePi RV2 booting Alpine Linux. Below are some additional configurations to help make growing your install a little easier. The following assumes you're still chroot /mnt or have booted the system.

=== Add a local user for yourself with escalation privileges ===

Create a user account for yourself with a secondary group of wheel
<pre># Create your account
useradd -G wheel -s /bin/bash -d /home/myuser -m -c "My User" myuser
# Set your password
passwd myuser</pre>

Add a configuration to doas.d for group wheel
<pre>echo permit persist :wheel > /etc/doas.d/00-wheel.conf</pre>

=== Install Avahi for mdns broadcasts ===

Avahi can broadcast names for services provided by your host. The default config in the Alpine package provides a configuration for sshd.

<pre># First setup the hostname
setup-hostname myhost

# Set the hostname
hostname `cat /etc/hostname`

# Install the avahi apk
apk add avahi

# Enable and start the avahi daemon
rc-update add avahi-daemon && rc-service avahi-daemon start</pre>

[[Category:Riscv64]]

Installing Alpine Linux on OrangePi RV2

2026-04-10T03:16:24Z

Aarch0x40:

{{Draft}}
[[Main Page]] > [[:Category:Architectures|Architectures]] > [[Riscv64]] > Installing Alpine Linux on OrangePi RV2
 
{{Warning|The contributors to the Alpine Linux project are not responsible for any damage/loss experienced by using the following guide. This article is provided as a general reference. It is assumed that the implementer will have the knowledge and ability to close the gap between what is described here and their specific setup.}}

The [http://www.orangepi.org/html/hardWare/computerAndMicrocontrollers/details/Orange-Pi-RV2.html OrangePi RV2] is a credit-card sized development board with a Ky X1 8-Core SoC. The Ky X1 is for all intents and purposes a SpacemiT K1 SoC. The remainder of this guide is more likely to use the terms SpacemiT or K1 as is prevalent throughout the Linux community. Please understand that these terms all refer to the same RISC-V ISA implementation.

This guide assumes that the manufacturer provided [https://github.com/riscv-software-src/opensbi OpenSBI] and [https://u-boot.org/ U-Boot] binaries have been applied to the SPI Flash device. This stock bootloader will look for an <code>extlinux/extlinux.conf</code> which will be used to configure the boot process.

Those following this guide may find it useful to have a USB UART serial cable available to debug kernel loading.

This guide borrows heavily from the article [https://arvanta.net/alpine/install-alpine-riscv64-qemu-uboot/ install Alpine Linux riscv64 under qemu with u-boot loader] by Milan P. Stanić and posted to [[Riscv64]] by [[User:AnIDFB]].

== Known issues ==
 
{{Warning|The following are the issues that are known to exist between the result of this guide and the manufacturer provided image}}

* Wireless (Wi-Fi & Bluetooth) is not functional
* Some kernel sources have an issue with starting the framebuffer
* Manufacturer tools are not included

== Kernel and Firmware ==
There are a few different options for kernels. The extent of coverage documented here is largely due to my initial ignorance. I have found a few sources for mostly workable kernels. None of them works 100%. SpacemiT is still in the process upstreaming functionality.

=== Obtaining the ESOS firmware ===
The processor being used on the RV2 requires a firmware to function properly. This file is available from the vendor images, in third party distributions and in the [https://github.com/orangepi-xunlong/orangepi-build orangepi-xunlong/orangepi-build] GitHub repository. The subdirectory containing the required file is [https://github.com/orangepi-xunlong/orangepi-build/tree/next/external/packages/bsp/ky/usr/lib/firmware external/packages/bsp/ky/usr/lib/firmware]. Download the file <code>esos.elf</code>. Keep the download in a safe place and also <code>/lib/firmware</code>. The <code>/lib/firmware</code> directory is also where you'll find this file within the vendor's image or an initrd image.
{{Note|
Changes to mkinitfs will be needed in order for this firmware to be included. More information on that will be provided further down the document}}
=== Obtaining the Vendor kernel ===
Open a browser to the [http://www.orangepi.org/html/hardWare/computerAndMicrocontrollers/service-and-support/Orange-Pi-RV2.html OrangePI RV2 Download] page.
=== Will Alpine's kernel work? (TBD) ===
{{Note|
Need to revisit this}}
=== Building from source ===
There have been 2 main repositories for patched kernel sources.

* [https://github.com/jasonmontleon/linux-spacemit jasonmontleon/linux-spacemit]
* [https://github.com/BredOS/linux-bredos BredOS/linux-bredos]

The linux-spacemit repository is used by RedHat employee Jason Montleon in building out their RISCV64 support. The linux-bredos repository is used by the BredOS project which supports the RV2 and has provides downloadable images for the board. There is cross contribution between these two repositories. A lot of what I've learned to assemble this guide is attributed to these projects.

==== Setting up a workspace ====

Begin by setting up a RISC-V workspace by following [[Riscv64|Running Alpine riscv64 in QEMU]]. You'll need to establish a build environment in this QEMU guest.

<pre>doas apk add alpine-sdk bison flex openssl-dev ncurses ncurses-dev</pre>

{{Note|
<code>ncurses</code> and <code>ncurses-dev</code> aren't a hard requirements but are useful if you want to run <code>make menuconfig</code>}}

==== Cloning the source, configuring and building the kernel ====

Unfortunately the stock kernels provided by the Alpine Linux project and even the source tarballs from kernel.org will not work. There's still a bit of patchwork involved as not all support is up-streamed. Fortunately there is someone who is maintaining repository with patched kernel sources. These sources are current to 6.18.20.

The following command will clone just the current HEAD of the patched repository

<pre>git clone --depth 1 https://github.com/jasonmontleon/linux-spacemit.git
cd linux-spacemit
make ARCH=riscv k1_defconfig
make -j$(nproc)</pre>

{{Note|
The kernel build may fail. I recommend starting with the k1_defconfig and working through errors as they come up. Only the RealTek 8852BS was an issue at the time of this writing.}}

== Preparing the media ==

=== Partition and setup the filesystems ===
==== Install parted package ====
<pre>doas apk add parted</pre>
==== Insert, partition and format the boot media ====

The media can be either an SD card or USB drive. An 2280 PCIe NVMe is also possibly if you have the ability to write it from the host setting up the media. For the purposes of this guide we will refer to our boot media as <code>/dev/sdb</code>. The following section requires a root shell.

<pre>alias p="parted -sa optimal /dev/sdb"
p mklabel gpt
p mkpart boot ext4 0G 512M
p set 1 boot
p mkpart root ext4 512M 100%
p p</pre>

The final command should produce output to confirm the result of the executed commands. It should look something like the following.

<pre>Model: Generic STORAGE DEVICE (scsi)
Disk /dev/sdb: 15.5GB
Sector size (logical/physical): 512B/512B
Partition Table: gpt
Disk Flags:

Number Start End Size File system Name Flags
1 1049kB 512MB 511MB ext4 boot boot, esp
2 512MB 15.5GB 15.0GB root
</pre>

If all looks good, then we can proceed with formatting the partitions

<pre>mkfs.ext4 /dev/sdb1 && mkfs.ext4 /dev/sdb2</pre>

Mount the filesystems and lay some preliminary groundwork.

<pre># Mount the target root slice
mount /dev/sdb2 /mnt

# Create mount point for boot slice
[ ! -d /mnt/boot ] && mkdir -vp /mnt/boot

# Mount boot slice
mount /dev/sdb1 /mnt/boot

# Create directory for extlinux config
[ ! -d /mnt/boot/extlinux ] && mkdir -vp /mnt/boot/extlinux

# Create directory for apk config
[ ! -d /mnt/etc/apk ] && mkdir -vp /mnt/etc/apk

# Create mount point for devfs
[ ! -d /mnt/dev ] && mkdir -vp /mnt/dev

# Create mount point for procfs
[ ! -d /mnt/proc ] && mkdir -vp /mnt/proc

# Create mount point for sysfs
[ ! -d /mnt/sys ] && mkdir -vp /mnt/sys

# Use bind mounts for dev proc and sys within the target device
mount -o bind /dev /mnt/dev && mount -o bind /proc /mnt/proc && mount -o bind /sys /mnt/sys

# Configure apk package manager
cat <<EOF > /mnt/etc/apk/repositories
#/media/vda1/apks
http://dl-cdn.alpinelinux.org/alpine/edge/main
http://dl-cdn.alpinelinux.org/alpine/edge/community
http://dl-cdn.alpinelinux.org/alpine/edge/testing
EOF
</pre>
== Install Alpine from an Alpine host ==

=== Install Alpine with apk ===
Some of what is going to be installed is up to your choosing. This should be enough to get you going and demonstrate how to target an apk installation.
<pre>apk --root /mnt --arch riscv64 --allow-untrusted --initdb add \
alpine-base alpine-baselayout alpine-conf alpine-keys alpine-release alpine-baselayout-data \
kmod openrc dbus util-linux blkid chrony sysfsutils ssl_client openssh ca-certificates-bundle \
alpine-keys ethtool e2fsprogs e2fsprogs-extra libudev-zero libudev-zero-helper parted grep \
busybox-mdev-openrc procps-ng net-tools coreutils doas sed gawk findutils bash shadow pciutils \
mkinitfs</pre>

=== Setup openrc services ===
<pre>for rc in boot/bootmisc boot/hostname boot/modules boot/sysctl boot/urandom boot/networking \
sysinit/devfs sysinit/hwdrivers sysinit/mdev sysinit/modules \
shutdown/mount-ro shutdown/killprocs \
default/dbus default/networking default/chronyd default/local; do
ln -s /etc/init.d/"${rc##*/}" /mnt/etc/runlevels/"$rc"
done</pre>

=== Setup fstab ===
<pre>cp /mnt/etc/fstab /mnt/etc/fstab.orig
echo $(blkid /dev/sdb2 | sed 's/.*: //;s/ .*//;s/"//g') / \ \ \ \ ext4 rw,relatime 0 1 > /mnt/etc/fstab.new
echo $(blkid /dev/sdb1 | sed 's/.*: //;s/ .*//;s/"//g') /boot ext4 rw,relatime 0 2 >> /mnt/etc/fstab.new
cat /mnt/etc/fstab.orig >> /mnt/etc/fstab.new
cp /mnt/etc/fstab.new /mnt/etc/fstab</pre>

=== Setup networking ===
<pre>[ ! -d /mnt/etc/network ] mkdir -vp /mnt/etc/networking
cat <<EOF > /mnt/etc/network/interfaces
auto lo
iface lo inet loopback

auto eth0
iface eth0 inet dhcp

EOF</pre>

=== Set the root password ===
When the system boots it will require a root password. This differs from Alpine install media but that's not the objective of this guide. This guide is installing a ready system.

<pre>passwd -R /mnt root</pre>

=== Enable login on UART ===
<pre>sed -i 's/^#ttyS0/ttyS0/' /mnt/etc/inittab</pre>

== Install Alpine from an non-Alpine RISC-V Linux host ==

=== Download a minirootfs to run apk within a chroot ===
<pre>cd /var/tmp
wget https://dl-cdn.alpinelinux.org/edge/releases/riscv64/alpine-minirootfs-20260127-riscv64.tar.gz</pre>
Unzip in /mnt
<pre>cd /mnt
tar xfpz /var/tmp/alpine-minirootfs-20260127-riscv64.tar.gz</pre>
{{Note|
If installing from a non-Alpine host, you may want to install the kernel image and modules first. Come back to this part to chroot and run the apk step and finish up with mkinitfs}}
Chroot into /mnt and run <code>apk add</code>
<pre>chroot /mnt /bin/sh
apk --arch riscv64 --allow-untrusted --initdb add \
alpine-base alpine-baselayout alpine-conf alpine-keys alpine-release alpine-baselayout-data \
kmod openrc dbus util-linux blkid chrony sysfsutils ssl_client openssh ca-certificates-bundle \
alpine-keys ethtool e2fsprogs e2fsprogs-extra libudev-zero libudev-zero-helper parted grep \
busybox-mdev-openrc procps-ng net-tools coreutils doas sed gawk findutils bash shadow pciutils \
mkinitfs</pre>

=== Setup openrc services ===
<pre>for rc in boot/bootmisc boot/hostname boot/modules boot/sysctl boot/urandom boot/networking \
sysinit/devfs sysinit/hwdrivers sysinit/mdev sysinit/modules \
shutdown/mount-ro shutdown/killprocs \
default/dbus default/networking default/chronyd default/local; do
ln -s /etc/init.d/"${rc##*/}" /etc/runlevels/"$rc"
done</pre>

=== Setup fstab within the chroot ===
<pre>cp /etc/fstab /etc/fstab.orig
echo $(blkid /dev/sdb2 | sed 's/.*: //;s/ .*//;s/"//g') / \ \ \ \ ext4 rw,relatime 0 1 > /etc/fstab.new
echo $(blkid /dev/sdb1 | sed 's/.*: //;s/ .*//;s/"//g') /boot ext4 rw,relatime 0 2 >> /etc/fstab.new
cat /etc/fstab.orig >> /etc/fstab.new
cp /etc/fstab.new /etc/fstab</pre>

=== Setup networking ===
<pre>[ ! -d /etc/network ] mkdir -vp /etc/networking
cat <<EOF > /etc/network/interfaces
auto lo
iface lo inet loopback

auto eth0
iface eth0 inet dhcp

EOF</pre>

=== Set the root password ===
When the system boots it will require a root password. This differs from Alpine install media but that's not the objective of this guide. This guide is installing a ready system.

<pre>passwd</pre>

=== Enable login on UART ===
<pre>sed -i 's/^#ttyS0/ttyS0/' /etc/inittab</pre>

== Setting up the boot environment ==
All of the effort up to this point has come down to this. This portion of the guide will assume the kernel being installed is version 6.6.63-ky from the vendor.
=== Install the kernel ===
=== Install the esos.elf firmware ===
=== Creating the initrd image ===
==== Configuring and fixing mkinitfs ====
===== Add esos.elf to mkinitfs/features.d/base.files =====
<pre>echo "/lib/firmware/esos.elf" >> /etc/mkinitfs/features.d/base.files</pre>
===== Add the wireless-regdb database files to base.files =====
{{Note|
You may not need this. If you see a kernel message regarding failure to load regulatory.db with error -2, this will resolve it}}
<pre>echo "/lib/firmware/regulatory.*" >> /etc/mkinitfs/features.d/base.files</pre>
===== Add jdb2 to ext4 =====
The ext4 module depends on the jdb2 module for filesystem journaling. The Alpine kernel does not have ext4 or jbd2 as kernel builtins. If you're using the Alpine provided kernel then you'll need this on the initramfs.
<pre>echo "kernel/fs/jbd2" >> /etc/mkinitfs/features.d/ext4.modules</pre>
===== Prevent mkinitfs from deleting needed firmware =====
The mkinitfs script will delete a directory that shouldn't exist. The files assembled from the features.d includes will have already been staged prior to mkinitfs assembling firmware needed by included modules. We need this not to happen and below is the simplest workaround I could pull together.
Make a copy of mkinitfs
<pre>cp /sbin/mkinitfs /sbin/mkinitfs-rv2</pre>
In the initfs_firmware function of <code>/sbin/mkinitfs-rv2</code> you will find the following lines
<pre> rm -rf "$tmpdir"/lib/firmware
mkdir -p "$tmpdir"/lib/firmware</pre>
Change them to be
<pre> #rm -rf "$tmpdir"/lib/firmware
[ ! -d "$tmpdir"/lib/firmware ] && mkdir -p "$tmpdir"/lib/firmware</pre>

==== Using mkinitfs-rv2 to create an initrd image ====
=== Configure extlinux ===

== Basic usability options ==

The above should get your OrangePi RV2 booting Alpine Linux. Below are some additional configurations to help make growing your install a little easier. The following assumes you're still chroot /mnt or have booted the system.

=== Add a local user for yourself with escalation privileges ===

Create a user account for yourself with a secondary group of wheel
<pre># Create your account
useradd -G wheel -s /bin/bash -d /home/myuser -m -c "My User" myuser
# Set your password
passwd myuser</pre>

Add a configuration to doas.d for group wheel
<pre>echo permit persist :wheel > /etc/doas.d/00-wheel.conf</pre>

=== Install Avahi for mdns broadcasts ===

Avahi can broadcast names for services provided by your host. The default config in the Alpine package provides a configuration for sshd.

<pre># First setup the hostname
setup-hostname myhost

# Set the hostname
hostname `cat /etc/hostname`

# Install the avahi apk
apk add avahi

# Enable and start the avahi daemon
rc-update add avahi-daemon && rc-service avahi-daemon start</pre>

[[Category:Riscv64]]

Installing Alpine Linux on OrangePi RV2

2026-04-10T02:57:52Z

Aarch0x40:

{{Draft}}
[[Main Page]] > [[:Category:Architectures|Architectures]] > [[Riscv64]] > Installing Alpine Linux on OrangePi RV2
 
{{Warning|The contributors to the Alpine Linux project are not responsible for any damage/loss experienced by using the following guide. This article is provided as a general reference. It is assumed that the implementer will have the knowledge and ability to close the gap between what is described here and their specific setup.}}

The [http://www.orangepi.org/html/hardWare/computerAndMicrocontrollers/details/Orange-Pi-RV2.html OrangePi RV2] is a credit-card sized development board with a Ky X1 8-Core SoC. The Ky X1 is for all intents and purposes a SpacemiT K1 SoC. The remainder of this guide is more likely to use the terms SpacemiT or K1 as is prevalent throughout the Linux community. Please understand that these terms all refer to the same RISC-V ISA implementation.

This guide assumes that the manufacturer provided [https://github.com/riscv-software-src/opensbi OpenSBI] and [https://u-boot.org/ U-Boot] binaries have been applied to the SPI Flash device. This stock bootloader will look for an <code>extlinux/extlinux.conf</code> which will be used to configure the boot process.

Those following this guide may find it useful to have a USB UART serial cable available to debug kernel loading.

This guide borrows heavily from the article [https://arvanta.net/alpine/install-alpine-riscv64-qemu-uboot/ install Alpine Linux riscv64 under qemu with u-boot loader] by Milan P. Stanić and posted to [[Riscv64]] by [[User:AnIDFB]].

== Known issues ==
 
{{Warning|The following are the issues that are known to exist between the result of this guide and the manufacturer provided image}}

* Wireless (Wi-Fi & Bluetooth) is not functional
* Manufacturer tools are not included

== Kernel and Firmware ==
=== Obtaining the ESOS firmware ===
The processor being used on the RV2 requires a firmware to function properly. This file is available from the vendor images, in third party distributions and in the [https://github.com/orangepi-xunlong/orangepi-build orangepi-xunlong/orangepi-build] GitHub repository. The subdirectory containing the required file is [https://github.com/orangepi-xunlong/orangepi-build/tree/next/external/packages/bsp/ky/usr/lib/firmware external/packages/bsp/ky/usr/lib/firmware]. Download the file <code>esos.elf</code>. Keep the download in a safe place and also <code>/lib/firmware</code>. The <code>/lib/firmware</code> directory is also where you'll find this file within the vendor's image or an initrd image.
{{Note|
Changes to mkinitfs will be needed in order for this firmware to be included. More information on that will be provided further down the document}}
=== Obtaining the Vendor kernel ===
Open a browser to the [http://www.orangepi.org/html/hardWare/computerAndMicrocontrollers/service-and-support/Orange-Pi-RV2.html OrangePI RV2 Download] page.
=== Will Alpine's kernel work? (TBD) ===
{{Note|
Need to revisit this}}
=== Building from source ===
==== Setting up a workspace ====

Begin by setting up a RISC-V workspace by following [[Riscv64|Running Alpine riscv64 in QEMU]]. You'll need to establish a build environment in this QEMU guest.

<pre>doas apk add alpine-sdk bison flex openssl-dev ncurses ncurses-dev</pre>

{{Note|
<code>ncurses</code> and <code>ncurses-dev</code> aren't a hard requirements but are useful if you want to run <code>make menuconfig</code>}}

==== Cloning the source, configuring and building the kernel ====

Unfortunately the stock kernels provided by the Alpine Linux project and even the source tarballs from kernel.org will not work. There's still a bit of patchwork involved as not all support is up-streamed. Fortunately there is someone who is maintaining repository with patched kernel sources. These sources are current to 6.18.20.

The following command will clone just the current HEAD of the patched repository

<pre>git clone --depth 1 https://github.com/jasonmontleon/linux-spacemit.git
cd linux-spacemit
make ARCH=riscv k1_defconfig
make -j$(nproc)</pre>

{{Note|
The kernel build may fail. I recommend starting with the k1_defconfig and working through errors as they come up. Only the RealTek 8852BS was an issue at the time of this writing.}}

== Preparing the media ==

=== Partition and setup the filesystems ===
==== Install parted package ====
<pre>doas apk add parted</pre>
==== Insert, partition and format the boot media ====

The media can be either an SD card or USB drive. An 2280 PCIe NVMe is also possibly if you have the ability to write it from the host setting up the media. For the purposes of this guide we will refer to our boot media as <code>/dev/sdb</code>. The following section requires a root shell.

<pre>alias p="parted -sa optimal /dev/sdb"
p mklabel gpt
p mkpart boot ext4 0G 512M
p set 1 boot
p mkpart root ext4 512M 100%
p p</pre>

The final command should produce output to confirm the result of the executed commands. It should look something like the following.

<pre>Model: Generic STORAGE DEVICE (scsi)
Disk /dev/sdb: 15.5GB
Sector size (logical/physical): 512B/512B
Partition Table: gpt
Disk Flags:

Number Start End Size File system Name Flags
1 1049kB 512MB 511MB ext4 boot boot, esp
2 512MB 15.5GB 15.0GB root
</pre>

If all looks good, then we can proceed with formatting the partitions

<pre>mkfs.ext4 /dev/sdb1 && mkfs.ext4 /dev/sdb2</pre>

Mount the filesystems and lay some preliminary groundwork.

<pre># Mount the target root slice
mount /dev/sdb2 /mnt

# Create mount point for boot slice
[ ! -d /mnt/boot ] && mkdir -vp /mnt/boot

# Mount boot slice
mount /dev/sdb1 /mnt/boot

# Create directory for extlinux config
[ ! -d /mnt/boot/extlinux ] && mkdir -vp /mnt/boot/extlinux

# Create directory for apk config
[ ! -d /mnt/etc/apk ] && mkdir -vp /mnt/etc/apk

# Create mount point for devfs
[ ! -d /mnt/dev ] && mkdir -vp /mnt/dev

# Create mount point for procfs
[ ! -d /mnt/proc ] && mkdir -vp /mnt/proc

# Create mount point for sysfs
[ ! -d /mnt/sys ] && mkdir -vp /mnt/sys

# Use bind mounts for dev proc and sys within the target device
mount -o bind /dev /mnt/dev && mount -o bind /proc /mnt/proc && mount -o bind /sys /mnt/sys

# Configure apk package manager
cat <<EOF > /mnt/etc/apk/repositories
#/media/vda1/apks
http://dl-cdn.alpinelinux.org/alpine/edge/main
http://dl-cdn.alpinelinux.org/alpine/edge/community
http://dl-cdn.alpinelinux.org/alpine/edge/testing
EOF
</pre>
== Install Alpine from an Alpine host ==

=== Install Alpine with apk ===
Some of what is going to be installed is up to your choosing. This should be enough to get you going and demonstrate how to target an apk installation.
<pre>apk --root /mnt --arch riscv64 --allow-untrusted --initdb add \
alpine-base alpine-baselayout alpine-conf alpine-keys alpine-release alpine-baselayout-data \
kmod openrc dbus util-linux blkid chrony sysfsutils ssl_client openssh ca-certificates-bundle \
alpine-keys ethtool e2fsprogs e2fsprogs-extra libudev-zero libudev-zero-helper parted grep \
busybox-mdev-openrc procps-ng net-tools coreutils doas sed gawk findutils bash shadow pciutils \
mkinitfs</pre>

=== Setup openrc services ===
<pre>for rc in boot/bootmisc boot/hostname boot/modules boot/sysctl boot/urandom boot/networking \
sysinit/devfs sysinit/hwdrivers sysinit/mdev sysinit/modules \
shutdown/mount-ro shutdown/killprocs \
default/dbus default/networking default/chronyd default/local; do
ln -s /etc/init.d/"${rc##*/}" /mnt/etc/runlevels/"$rc"
done</pre>

=== Setup fstab ===
<pre>cp /mnt/etc/fstab /mnt/etc/fstab.orig
echo $(blkid /dev/sdb2 | sed 's/.*: //;s/ .*//;s/"//g') / \ \ \ \ ext4 rw,relatime 0 1 > /mnt/etc/fstab.new
echo $(blkid /dev/sdb1 | sed 's/.*: //;s/ .*//;s/"//g') /boot ext4 rw,relatime 0 2 >> /mnt/etc/fstab.new
cat /mnt/etc/fstab.orig >> /mnt/etc/fstab.new
cp /mnt/etc/fstab.new /mnt/etc/fstab</pre>

=== Setup networking ===
<pre>[ ! -d /mnt/etc/network ] mkdir -vp /mnt/etc/networking
cat <<EOF > /mnt/etc/network/interfaces
auto lo
iface lo inet loopback

auto eth0
iface eth0 inet dhcp

EOF</pre>

=== Set the root password ===
When the system boots it will require a root password. This differs from Alpine install media but that's not the objective of this guide. This guide is installing a ready system.

<pre>passwd -R /mnt root</pre>

=== Enable login on UART ===
<pre>sed -i 's/^#ttyS0/ttyS0/' /mnt/etc/inittab</pre>

== Install Alpine from an non-Alpine RISC-V Linux host ==

=== Download a minirootfs to run apk within a chroot ===
<pre>cd /var/tmp
wget https://dl-cdn.alpinelinux.org/edge/releases/riscv64/alpine-minirootfs-20260127-riscv64.tar.gz</pre>
Unzip in /mnt
<pre>cd /mnt
tar xfpz /var/tmp/alpine-minirootfs-20260127-riscv64.tar.gz</pre>
{{Note|
If installing from a non-Alpine host, you may want to install the kernel image and modules first. Come back to this part to chroot and run the apk step and finish up with mkinitfs}}
Chroot into /mnt and run <code>apk add</code>
<pre>chroot /mnt /bin/sh
apk --arch riscv64 --allow-untrusted --initdb add \
alpine-base alpine-baselayout alpine-conf alpine-keys alpine-release alpine-baselayout-data \
kmod openrc dbus util-linux blkid chrony sysfsutils ssl_client openssh ca-certificates-bundle \
alpine-keys ethtool e2fsprogs e2fsprogs-extra libudev-zero libudev-zero-helper parted grep \
busybox-mdev-openrc procps-ng net-tools coreutils doas sed gawk findutils bash shadow pciutils \
mkinitfs</pre>

=== Setup openrc services ===
<pre>for rc in boot/bootmisc boot/hostname boot/modules boot/sysctl boot/urandom boot/networking \
sysinit/devfs sysinit/hwdrivers sysinit/mdev sysinit/modules \
shutdown/mount-ro shutdown/killprocs \
default/dbus default/networking default/chronyd default/local; do
ln -s /etc/init.d/"${rc##*/}" /etc/runlevels/"$rc"
done</pre>

=== Setup fstab within the chroot ===
<pre>cp /etc/fstab /etc/fstab.orig
echo $(blkid /dev/sdb2 | sed 's/.*: //;s/ .*//;s/"//g') / \ \ \ \ ext4 rw,relatime 0 1 > /etc/fstab.new
echo $(blkid /dev/sdb1 | sed 's/.*: //;s/ .*//;s/"//g') /boot ext4 rw,relatime 0 2 >> /etc/fstab.new
cat /etc/fstab.orig >> /etc/fstab.new
cp /etc/fstab.new /etc/fstab</pre>

=== Setup networking ===
<pre>[ ! -d /etc/network ] mkdir -vp /etc/networking
cat <<EOF > /etc/network/interfaces
auto lo
iface lo inet loopback

auto eth0
iface eth0 inet dhcp

EOF</pre>

=== Set the root password ===
When the system boots it will require a root password. This differs from Alpine install media but that's not the objective of this guide. This guide is installing a ready system.

<pre>passwd</pre>

=== Enable login on UART ===
<pre>sed -i 's/^#ttyS0/ttyS0/' /etc/inittab</pre>

== Setting up the boot environment ==
All of the effort up to this point has come down to this. This portion of the guide will assume the kernel being installed is version 6.6.63-ky from the vendor.
=== Install the kernel ===
=== Install the esos.elf firmware ===
=== Creating the initrd image ===
==== Configuring and fixing mkinitfs ====
===== Add esos.elf to mkinitfs/features.d/base.files =====
<pre>echo "/lib/firmware/esos.elf" >> /etc/mkinitfs/features.d/base.files</pre>
===== Add the wireless-regdb database files to base.files =====
{{Note|
You may not need this. If you see a kernel message regarding failure to load regulatory.db with error -2, this will resolve it}}
<pre>echo "/lib/firmware/regulatory.*" >> /etc/mkinitfs/features.d/base.files</pre>
===== Add jdb2 to ext4 =====
The ext4 module depends on the jdb2 module for filesystem journaling. The Alpine kernel does not have ext4 or jbd2 as kernel builtins. If you're using the Alpine provided kernel then you'll need this on the initramfs.
<pre>echo "kernel/fs/jbd2" >> /etc/mkinitfs/features.d/ext4.modules</pre>
===== Prevent mkinitfs from deleting needed firmware =====
The mkinitfs script will delete a directory that shouldn't exist. The files assembled from the features.d includes will have already been staged prior to mkinitfs assembling firmware needed by included modules. We need this not to happen and below is the simplest workaround I could pull together.
Make a copy of mkinitfs
<pre>cp /sbin/mkinitfs /sbin/mkinitfs-rv2</pre>
In the initfs_firmware function of <code>/sbin/mkinitfs-rv2</code> you will find the following lines
<pre> rm -rf "$tmpdir"/lib/firmware
mkdir -p "$tmpdir"/lib/firmware</pre>
Change them to be
<pre> #rm -rf "$tmpdir"/lib/firmware
[ ! -d "$tmpdir"/lib/firmware ] && mkdir -p "$tmpdir"/lib/firmware</pre>

==== Using mkinitfs-rv2 to create an initrd image ====
=== Configure extlinux ===

== Basic usability options ==

The above should get your OrangePi RV2 booting Alpine Linux. Below are some additional configurations to help make growing your install a little easier. The following assumes you're still chroot /mnt or have booted the system.

=== Add a local user for yourself with escalation privileges ===

Create a user account for yourself with a secondary group of wheel
<pre># Create your account
useradd -G wheel -s /bin/bash -d /home/myuser -m -c "My User" myuser
# Set your password
passwd myuser</pre>

Add a configuration to doas.d for group wheel
<pre>echo permit persist :wheel > /etc/doas.d/00-wheel.conf</pre>

=== Install Avahi for mdns broadcasts ===

Avahi can broadcast names for services provided by your host. The default config in the Alpine package provides a configuration for sshd.

<pre># First setup the hostname
setup-hostname myhost

# Set the hostname
hostname `cat /etc/hostname`

# Install the avahi apk
apk add avahi

# Enable and start the avahi daemon
rc-update add avahi-daemon && rc-service avahi-daemon start</pre>

[[Category:Riscv64]]

Installing Alpine Linux on OrangePi RV2

2026-04-10T02:11:24Z

Aarch0x40:

Installing Alpine Linux on OrangePi RV2

2026-04-10T01:23:44Z

Aarch0x40:

Riscv64

2026-04-10T01:16:15Z

Aarch0x40:

{{TOC right}}
{{Move|Running Alpine riscv64 in QEMU|Relocate this current page to one specific to QEMU. This page would then become a list of articles related to installing Alpine Linux on specific RISCV66 hardware implementations. The new location of this article would be listed on the new page. A preview of the new page can be found [[Riscv64 Redo|here]]}}
riscv64 (RISC-V 64-bit) is one of the [[architecture|architectures]] that Alpine Linux supports. The first stable release was Alpine Linux 3.20. Standard ISO images are available since Alpine Linux 3.23. You can download it from the [https://alpinelinux.org/downloads/ Alpine Linux downloads] page.

== Running Alpine riscv64 in QEMU ==

=== Installing QEMU on Alpine ===

Installing QEMU for RISC-V on Alpine is very straightforward:

{{Cmd|# apk add qemu-system-riscv64 qemu-img}}

You will need {{Pkg|qemu-img|arch=riscv64}} if you want to create QCOW2 disk images; if you only want to create raw images, it’s not needed.

For example, to create a new 2 GB QCOW2 disk image:

{{Cmd|$ qemu-img create -f qcow2 alpine-riscv64.qcow2 2G}}

Adjust the ''size'' parameter as you see fit.

=== Getting U-Boot ===

[https://u-boot.org/ U-Boot], aka ''Das U-Boot: The Universal Boot Loader'', is one of the easiest, most flexible ways to boot Alpine on RISC-V. It can be used with GRUB for EFI booting, or with <code>extlinux.conf</code> for non-EFI booting.

You need the file '''<code>u-boot.bin</code>''' to boot using U-Boot. Alpine provides a compiled <code>u-boot.bin</code> in two places:

# The '''Generic U-Boot tarball''' on the [https://alpinelinux.org/downloads/ Alpine downloads page]. Currently that is:
#:https://dl-cdn.alpinelinux.org/alpine/v3.23/releases/riscv64/alpine-uboot-3.23.3-riscv64.tar.gz
# The '''[https://pkgs.alpinelinux.org/package/edge/main/riscv64/u-boot-qemu <code>u-boot-qemu</code> package for <code>riscv64</code>]'''. Note that if you are not already on an Alpine riscv64 system, you won’t be able to just <code>apk add</code> this package, as it will be for a different architecture. In practical terms this means downloading the <code>.apk</code> file directly from an APK mirror, e.g.:
#:https://dl-cdn.alpinelinux.org/edge/main/riscv64/u-boot-qemu-2026.01-r0.apk

If you downloaded the <code>.tgz</code> file, this command will extract the <code>u-boot.bin</code> file to the current directory:

{{Cmd|$ tar --strip-components 3 -xf alpine-uboot-3.23.3-riscv64.tar.gz \
./u-boot/qemu-riscv64_smode/u-boot.bin}}

If you downloaded the <code>.apk</code> file, this command will extract the <code>u-boot.bin</code> file to the current directory:

{{Cmd|$ tar --strip-components 4 -xf u-boot-qemu-2026.01-r0.apk \
usr/share/u-boot/qemu-riscv64_smode/u-boot.bin}}

{{Note|There are two <code>u-boot.bin</code> files, but you need the one in the <code>qemu-riscv64_smode</code> directory. That is because OpenSBI (the first thing QEMU executes) will run in ''M-mode'' (the highest privilege), which expects to execute U-Boot in ''S-mode'' (one privilege level lower).}}

=== U-Boot + GRUB EFI ===

The easiest way to run Alpine riscv64 in EFI mode is to boot from the ISO. You can download it from the [https://alpinelinux.org/downloads/ Alpine downloads page]. Here is an example of launching QEMU using U-Boot to boot this ISO:

{{Cmd|$ qemu-system-riscv64 -machine virt -smp cores{{=}}2 -m 2G \
-nographic \
-kernel u-boot.bin \
-device virtio-rng-device \
-netdev user,hostfwd{{=}}tcp:127.0.0.1:2222-:22,id{{=}}n0 \
-device virtio-net-device,netdev{{=}}n0 \
-drive file{{=}}alpine-riscv64.qcow2,if{{=}}none,id{{=}}hd0 \
-device virtio-blk-device,drive{{=}}hd0 \
-drive file{{=}}alpine-standard-3.23.3-riscv64.iso,media{{=}}cdrom,if{{=}}none,id{{=}}cd0,readonly{{=}}on \
-device virtio-blk-device,drive{{=}}cd0}}

The boot path is therefore:

QEMU => OpenSBI => U-Boot => GRUB EFI => Linux

Some explanatory notes about the command:

* <code>-nographic</code> will select a serial console (rather than a graphical one).
* <code>-kernel u-boot.bin</code> is what causes OpenSBI to load U-Boot.
* The <code>-netdev</code> and <code>-device virtio-net-device</code> lines set up ''user-mode networking'' with SSH port forwarding from the host:2222 to the guest:22.
* The ISO is being treated as a <code>virtio-blk-device</code> rather than a real CD-ROM drive.
* After you’ve run <code>setup-alpine</code>, you can remove the last two lines on subsequent launches so the ISO is no longer attached.

It’s equally possible to boot using just the Generic U-Boot tarball. First, it needs to be fully extracted, ''except'' <code>extlinux.conf</code>, which U-Boot will try to use first if present:

{{Cmd|$ mkdir alpine-uboot-3.23.3-riscv64
$ tar -C alpine-uboot-3.23.3-riscv64 --exclude ./extlinux/extlinux.conf \
-xf alpine-uboot-3.23.3-riscv64.tar.gz}}

Then you can launch QEMU and have it emulate the <code>alpine-uboot-3.23.3-riscv64</code> as a [https://www.qemu.org/docs/master/system/images.html#virtual-fat-disk-images Virtual FAT disk image]:

{{Cmd|$ qemu-system-riscv64 -machine virt -smp cores{{=}}2 -m 2G \
-nographic \
-kernel u-boot.bin \
-device virtio-rng-device \
-netdev user,hostfwd{{=}}tcp:127.0.0.1:2222-:22,id{{=}}n0 \
-device virtio-net-device,netdev{{=}}n0 \
-drive file{{=}}alpine-riscv64.qcow2,if{{=}}none,id{{=}}hd0 \
-device virtio-blk-device,drive{{=}}hd0 \
-drive file{{=}}alpine-standard-3.23.3-riscv64.iso,media{{=}}cdrom,if{{=}}none,id{{=}}cd0,readonly{{=}}on \
-device virtio-blk-device,drive{{=}}hd1}}

This is nearly identical to the previous command, except the change from the ISO to the extracted tarball directory (<code>alpine-uboot-3.23.3-riscv64</code>). Note the <code>fat:ro:</code> syntax to emulate a virtual hard drive from a directory on the host.

=== U-Boot + extlinux.conf ===

U-Boot can use <code>extlinux.conf</code> to boot, which does not require EFI (and therefore does not use GRUB).

The simplest way to boot without EFI is to use the Generic U-Boot tarball. In this case, it’s extracted without modification and booted as a [https://www.qemu.org/docs/master/system/images.html#virtual-fat-disk-images Virtual FAT disk image].

First, extract the Generic U-Boot tarball:

{{Cmd|$ mkdir alpine-uboot-3.23.3-riscv64
$ tar -C alpine-uboot-3.23.3-riscv64 -xf alpine-uboot-3.23.3-riscv64.tar.gz}}

Then, launch QEMU:

{{Cmd|$ qemu-system-riscv64 -machine virt -smp cores{{=}}2 -m 2G \
-nographic \
-kernel u-boot.bin \
-device virtio-rng-device \
-netdev user,hostfwd{{=}}tcp:127.0.0.1:2222-:22,id{{=}}n0 \
-device virtio-net-device,netdev{{=}}n0 \
-drive file{{=}}alpine-riscv64.qcow2,if{{=}}none,id{{=}}hd0 \
-device virtio-blk-device,drive{{=}}hd0 \
-drive file{{=}}fat:ro:alpine-uboot-3.23.3-riscv64,if{{=}}none,id{{=}}hd1,readonly{{=}}on \
-device virtio-blk-device,drive{{=}}hd1}}

{{Warning|A [https://lists.denx.de/pipermail/u-boot/2025-August/596500.html regression exists in U-Boot 2025.10], which is included with the Alpine 3.23 release, that may prevent booting via <code>extlinux.conf</code>. The error will be similar to:

Failed to reserve memory for fdt at 0xbee9e220
FDT creation failed! hanging...### ERROR ### Please RESET the board ###

This has been [https://github.com/u-boot/u-boot/commit/62f1afbe7a8ae8f8b9e85c5ea4eb446b97892a7c resolved in U-Boot 2026.01].

'''Solution:''' use the <code>u-boot.bin</code> file from the Alpine Edge build of the {{Pkg|u-boot-qemu|arch=riscv64}} package, which will be U-Boot 2026.01 or later. See the ''[[#Getting_U-Boot|Getting U-Boot]]'' section for the URL and APK extraction instructions.}}

The boot path is therefore:

QEMU => OpenSBI => U-Boot + extlinux.conf => Linux

Some explanatory notes about the command:

* <code>-nographic</code> will select a serial console (rather than a graphical one).
* <code>-kernel u-boot.bin</code> is what causes OpenSBI to load U-Boot.
* The <code>-netdev</code> and <code>-device virtio-net-device</code> lines set up ''user-mode networking'' with SSH port forwarding from the host:2222 to the guest:22.
* After you’ve run <code>setup-alpine</code>, you can remove the last two lines on subsequent launches, so the virtual FAT disk image is no longer attached.

{{Tip|You may see a usage message that begins like:

usage: /usr/sbin/update-u-boot [-b{{!}}--board <board-type>] [-d{{!}}--device <device>]

This is harmless. If it concerns you, it can be suppressed during the install by using the <code>BOOTLOADER</code> environment variable:

{{Cmd|# BOOTLOADER{{=}}none setup-alpine}}
}}

(While it is technically possible to install from the ISO using <code>extlinux.conf</code>, doing so is more trouble than it’s worth, as you have to create a separate boot volume containing <code>/boot/vmlinuz-lts</code>, <code>/boot/initramfs-lts</code> from the ISO, and <code>/extlinux/extlinux.conf</code> from the Generic U-Boot tarball.)

=== EDK2 + GRUB EFI ===

Using EDK2 is convenient in that it comes bundled with {{Pkg|qemu-system-riscv64|arch=riscv64}}. However, it does require a few more QEMU options than U-Boot to work successfully.

Here is an example using EDK2 to boot the Alpine riscv64 standard ISO:

{{Cmd|$ cp /usr/share/qemu/edk2-riscv-vars.fd .
$ qemu-system-riscv64 -machine virt,acpi{{=}}off -smp cores{{=}}2 -m 2G \
-nographic \
-drive if{{=}}pflash,format{{=}}raw,unit{{=}}0,file{{=}}/usr/share/qemu/edk2-riscv-code.fd,readonly{{=}}on \
-drive if{{=}}pflash,format{{=}}raw,unit{{=}}1,file{{=}}edk2-riscv-vars.fd \
-device virtio-rng-device \
-netdev user,hostfwd{{=}}tcp:127.0.0.1:2222-:22,id{{=}}n0 \
-device virtio-net-device,netdev{{=}}n0 \
-drive file{{=}}alpine-riscv64.qcow2,if{{=}}none,id{{=}}hd0 \
-device virtio-blk-device,drive{{=}}hd0 \
-drive file{{=}}alpine-standard-3.23.3-riscv64.iso,media{{=}}cdrom,if{{=}}none,id{{=}}cd0,readonly{{=}}on \
-device virtio-blk-device,drive{{=}}cd0}}

{{Warning|EDK2 will not boot the kernel without <code>acpi{{=}}off</code>. It could be that the ACPI data QEMU is providing EDK2 is not compatible or accurate, somehow.}}

The boot path is:

QEMU => OpenSBI => EDK2 => GRUB EFI => Linux

Some explanatory notes about the command:

* <code>-nographic</code> will select a serial console (rather than a graphical one).
* The two <code>pflash</code> lines load two files:
** the EDK2 ''code'' in <code>readonly</code> mode.
** the EDK2 ''vars'' (EDK2’s nvram, essentially) in a writable way.
**:(EDK2 doesn’t load via <code>-kernel</code>, unlike U-Boot.)
* The <code>-netdev</code> and <code>-device virtio-net-device</code> lines set up ''user-mode networking'' with SSH port forwarding from the host:2222 to the guest:22.
* After you’ve run <code>setup-alpine</code>, you can remove the last two lines on subsequent launches, so the virtual FAT disk image is no longer attached.

{{Tip|EDK2 produces ''voluminous'' output before the Linux kernel starts. This is expected, even if seemingly abnormal.}}

=== Direct booting ===

“Direct” booting means using QEMU to load the kernel and initramfs files into memory and having OpenSBI boot them directly, bypassing any other bootloader such as U-Boot, EDK2, GRUB, etc. This is a very fast method of booting, but there are some points to consider:

* You will have to somehow get the kernel and initramfs onto the host system. During installation, this is straightforward enough: you can extract them out of the installation media. But for subsequent boots (ie, after <code>apk upgrade</code> has changed the kernel or initramfs in the guest), this becomes more challenging.
* Reboots will not use a new kernel from within the guest (ie, one downloaded via <code>apk upgrade</code>), but the one that was present on the host when QEMU was first launched. For this reason, it’s suggested that you use the <code>-noreboot</code> QEMU option to prevent reboots.
* Because there is no bootloader to pass kernel options, you must specify <code>-append</code> QEMU options instead. Fortunately these are rather standardized.

The boot path for this method is simply:

QEMU => OpenSBI => Linux

==== Extracting the images ====

To make extracting the images easier, here is a shell function you can use. It uses 7-Zip, which you can install on Alpine with <code>apk add {{Pkg|7zip|arch=riscv64}}</code>.

{{Cat|extract.sh|extract_boot_images() {
case "$1" in
iso{{!}}tar)
7z x -aoa "$2" boot/vmlinuz-lts boot/initramfs-lts
;;
hdimg)
7z x -aoa "$2" 0.img
7z x -aoa 0.img -oboot vmlinuz-lts initramfs-lts
rm -f 0.img
;;
esac
[ -f boot/vmlinuz-lts ] && gunzip < boot/vmlinuz-lts > boot/vmlinux-lts
}}}

This function takes two arguments: the file type, <code>iso</code>, <code>tar</code>, or <code>hdimg</code>, and the filename itself.

For the Alpine ISO or Generic U-Boot tarball, the extraction is fairly straightforward. For hard drive images (either QCOW2 or raw), it will extract the first partition (which ought to be <code>/boot</code>, ie, <code>/dev/vda1</code>), and then extract the images from that. In both cases, it decompresses <code>vmlinuz-lts</code> to <code>vmlinux-lts</code>, since it seems that OpenSBI wants an uncompressed kernel image.

{{Note|If you extract the kernel and initramfs from the ISO, you should use the ISO to install; and similarly, if you extract them from the Generic U-Boot tarball, you should use the tarball to install.}}

==== Install booting ====

Here is an example QEMU command line for installation booting (first using the shell script above to extract the images):

{{Cmd|$ . extract.sh
$ extract_boot_images iso alpine-standard-3.23.3-riscv64.iso
$ qemu-system-riscv64 -machine virt -smp cores{{=}}2 -m 2G \
-nographic \
-kernel boot/vmlinux-lts \
-initrd boot/initramfs-lts \
-append "modules{{=}}loop,squashfs,sd-mod,usb-storage quiet" \
-device virtio-rng-device \
-netdev user,hostfwd{{=}}tcp:127.0.0.1:2222-:22,id{{=}}n0 \
-device virtio-net-device,netdev{{=}}n0 \
-drive file{{=}}alpine-riscv64.qcow2,if{{=}}none,id{{=}}hd0 \
-device virtio-blk-device,drive{{=}}hd0 \
-drive file{{=}}alpine-standard-3.23.3-riscv64.iso,media{{=}}cdrom,if{{=}}none,id{{=}}cd0,readonly{{=}}on \
-device virtio-scsi-device,id{{=}}scsi0 \
-device scsi-cd,drive{{=}}cd0,bus{{=}}scsi0.0 \
-noreboot}}

Some explanatory notes about the command:

* <code>-nographic</code> will select a serial console (rather than a graphical one).
* The <code>-kernel</code>, <code>-initrd</code>, and <code>-append</code> lines set up the kernel boot from files on the host. The <code>-append</code> string is set up for booting from install media (the ISO or tarball).
* The <code>-netdev</code> and <code>-device virtio-net-device</code> lines set up ''user-mode networking'' with SSH port forwarding from the host:2222 to the guest:22.
* <code>-noreboot</code> prevents the system from rebooting back into the installer. (You should change the command post installation so that subsequent launches boot from your hard drive image.)

Run <code>setup-alpine</code> as normal. It may attempt to install a bootloader, but it won’t be used.

==== Normal booting ====

After the installation, you can run a normal boot by extracting the kernel and initramfs out of the hard drive image you just created:

{{Cmd|$ . extract.sh
$ extract_boot_images hdimg alpine-riscv64.qcow2
$ qemu-system-riscv64 -machine virt -smp cores{{=}}2 -m 2G \
-nographic \
-kernel boot/vmlinux-lts \
-initrd boot/initramfs-lts \
-append "root{{=}}/dev/vda3 modules{{=}}sd-mod,usb-storage,ext4 quiet rootfstype{{=}}ext4"
-device virtio-rng-device \
-netdev user,hostfwd{{=}}tcp:127.0.0.1:2222-:22,id{{=}}n0 \
-device virtio-net-device,netdev{{=}}n0 \
-drive file{{=}}alpine-riscv64.qcow2,if{{=}}none,id{{=}}hd0 \
-device virtio-blk-device,drive{{=}}hd0 \
-noreboot}}

The main difference here is in the image extraction (done using the hard drive image rather than the installation media) and in the <code>-append</code> line, which specifies the virtio disk <code>/dev/vda3</code> as the <code>root</code>.

Normally the <code>root</code> parameter would be a UUID. If you prefer to use a UUID, you can grab it using a command like:

{{Cmd|# blkid /dev/vda3}}

And update your <code>-append</code> parameter accordingly, e.g.:

{{Cmd| -append "root{{=}}UUID{{=}}2341d7cd-e050-427e-afff-94fa0db4c8c5 modules{{=}}sd-mod,usb-storage,ext4 quiet rootfstype{{=}}ext4" \}}

=== Using apk to create an image ===

Yet another way to create a hard drive image for Alpine riscv64 would be with the help of an existing Alpine system (using any architecture, not just riscv64). Here are two articles that discuss this method:

* [https://arvanta.net/alpine/install-alpine-riscv64-qemu/ install Alpine Linux riscv64 under qemu]
* [https://arvanta.net/alpine/install-alpine-riscv64-qemu-uboot/ install Alpine Linux riscv64 under qemu with u-boot loader]

{{Note|These articles were created for a previous version of Alpine, and there may be differences in the way that a current <code>setup-alpine</code> deploys a new system ''vs'' the result from these scripts. However, the techniques used are still sound and may be of interest.}}

== Contribute ==
* Test out the port and [https://gitlab.alpinelinux.org/alpine/aports/-/issues/?label_name%5B%5D=arch%3Ariscv64 report] the bugs you find.
* Write and improve guides about the port.
* Fix [https://gitlab.alpinelinux.org/alpine/aports packages] that are buggy or don't work on RISC-V.
''This section is based on [https://irclogs.alpinelinux.org/%23alpine-riscv64-2025-10.log this] [[Alpine Linux:IRC|IRC]] conversation from 2025-10-01.''

[[Category:Riscv64]]

Riscv64 Redo

2026-04-10T01:10:32Z

Aarch0x40:

{{Move|Riscv64|A new main page for RISCV64 that links to articles regarding specific hardware implementations. The current RISCV64 page would move to a QEMU specific one.}}
[[Main Page]] > [[architecture|Architectures]] > Riscv64

riscv64 (RISC-V 64-bit) is one of the [[architecture|architectures]] that Alpine Linux supports. The first stable release was Alpine Linux 3.20. Standard ISO images are available since Alpine Linux 3.23. You can download it from the [https://alpinelinux.org/downloads/ Alpine Linux downloads] page.

RISC-V is an open source instruction set architecture (ISA) that was originally developed at UC Berkeley. It's currently maintained by [https://riscv.org/ RISC-V International]. Organizations are allowed to implement the RISC-V ISA with their own custom extensions. This results in their being some specificity to each implementation that makes it to market. Below you'll find links to articles which detail how to get Alpine Linux running on your board or VM.

== Alpine Linux on Specific RISC-V Implementations ==
 
{{Warning|The contributors to the Alpine Linux project are not responsible for any damage/loss experienced by using the following guides. The following articles are provided as a general reference. It is assumed that the implementer will have the knowledge and ability to close the gap between what is described here and their specific setup.}}
* [[Riscv64|Running Alpine riscv64 in QEMU]]
* [[Installing Alpine Linux on OrangePi RV2]]

== Contribute ==
* Test out the port and [https://gitlab.alpinelinux.org/alpine/aports/-/issues/?label_name%5B%5D=arch%3Ariscv64 report] the bugs you find.
* Write and improve guides about the port.
* Fix [https://gitlab.alpinelinux.org/alpine/aports packages] that are buggy or don't work on RISC-V.
''This section is based on [https://irclogs.alpinelinux.org/%23alpine-riscv64-2025-10.log this] [[Alpine Linux:IRC|IRC]] conversation from 2025-10-01.''

[[Category:Riscv64]]

Installing Alpine Linux on OrangePi RV2

2026-04-03T01:04:26Z

Aarch0x40:

Riscv64 Redo

2026-03-29T21:42:14Z

Aarch0x40:

{{Draft}}
[[Main Page]] > [[architecture|Architectures]] > Riscv64

riscv64 (RISC-V 64-bit) is one of the [[architecture|architectures]] that Alpine Linux supports. The first stable release was Alpine Linux 3.20. Standard ISO images are available since Alpine Linux 3.23. You can download it from the [https://alpinelinux.org/downloads/ Alpine Linux downloads] page.

RISC-V is an open source instruction set architecture (ISA) that was originally developed at UC Berkeley. It's currently maintained by [https://riscv.org/ RISC-V International]. Organizations are allowed to implement the RISC-V ISA with their own custom extensions. This results in their being some specificity to each implementation that makes it to market. Below you'll find links to articles which detail how to get Alpine Linux running on your board or VM.

== Alpine Linux on Specific RISC-V Implementations ==
 
{{Warning|The contributors to the Alpine Linux project are not responsible for any damage/loss experienced by using the following guides. The following articles are provided as a general reference. It is assumed that the implementer will have the knowledge and ability to close the gap between what is described here and their specific setup.}}
* [[Riscv64|Running Alpine riscv64 in QEMU]]
* [[Installing Alpine Linux on OrangePi RV2]]

== Contribute ==
* Test out the port and [https://gitlab.alpinelinux.org/alpine/aports/-/issues/?label_name%5B%5D=arch%3Ariscv64 report] the bugs you find.
* Write and improve guides about the port.
* Fix [https://gitlab.alpinelinux.org/alpine/aports packages] that are buggy or don't work on RISC-V.
''This section is based on [https://irclogs.alpinelinux.org/%23alpine-riscv64-2025-10.log this] [[Alpine Linux:IRC|IRC]] conversation from 2025-10-01.''

[[Category:Riscv64]]

Installing Alpine Linux on OrangePi RV2

2026-03-29T21:41:49Z

Aarch0x40:

Installing Alpine Linux on OrangePi RV2

2026-03-29T21:30:29Z

Aarch0x40:

Installing Alpine Linux on OrangePi RV2

2026-03-29T21:29:49Z

Aarch0x40:

Installing Alpine Linux on OrangePi RV2

2026-03-29T21:23:36Z

Aarch0x40: /* Cloning the source, configuring and building the kernel */

Installing Alpine Linux on OrangePi RV2

2026-03-29T21:21:34Z

Aarch0x40: /* Extracting the vendor kernel */

Installing Alpine Linux on OrangePi RV2

2026-03-29T21:20:16Z

Aarch0x40: /* Downloading and extracting the vendor kernel */

Installing Alpine Linux on OrangePi RV2

2026-03-29T21:19:34Z

Aarch0x40:

Installing Alpine Linux on OrangePi RV2

2026-03-29T20:48:57Z

Aarch0x40: /* Cloning the source, configuring and building the kernel */

Installing Alpine Linux on OrangePi RV2

2026-03-29T20:48:44Z

Aarch0x40: /* Cloning the source, configuring and building the kernel */

Installing Alpine Linux on OrangePi RV2

2026-03-29T18:48:31Z

Aarch0x40: /* Install Alpine from an non-Alpine host */

Installing Alpine Linux on OrangePi RV2

2026-03-29T17:59:03Z

Aarch0x40: /* Setup fstab */

Installing Alpine Linux on OrangePi RV2

2026-03-29T17:58:47Z

Aarch0x40: /* Setup fstab */

Installing Alpine Linux on OrangePi RV2

2026-03-29T17:55:36Z

Aarch0x40:

Riscv64 Redo

2026-03-29T06:41:07Z

Aarch0x40:

{{Draft}}
[[Main Page]] > [[architecture|Architectures]] > Riscv64

riscv64 (RISC-V 64-bit) is one of the [[architecture|architectures]] that Alpine Linux supports. The first stable release was Alpine Linux 3.20. Standard ISO images are available since Alpine Linux 3.23. You can download it from the [https://alpinelinux.org/downloads/ Alpine Linux downloads] page.

RISC-V is an open source instruction set architecture (ISA) that was originally developed at UC Berkeley. It's currently maintained by [https://riscv.org/ RISC-V International]. Organizations are allowed to implement the RISC-V ISA with their own custom extensions. This results in their being some specificity to each implementation that makes it to market. Below you'll find links to articles which detail how to get Alpine Linux running on your board or VM.

== Alpine Linux on Specific RISC-V Implementations ==
 
{{Warning|The contributors to the Alpine Linux project are not responsible for any damage/loss experienced by using the following guides. The following articles are provided as a general reference to be adapted to your specific setup. It is assumed that the implementer will have the knowledge and ability to close the gap between what is described here and their specific setup.}}
* [[Riscv64|Running Alpine riscv64 in QEMU]]
* [[Installing Alpine Linux on OrangePi RV2]]

== Contribute ==
* Test out the port and [https://gitlab.alpinelinux.org/alpine/aports/-/issues/?label_name%5B%5D=arch%3Ariscv64 report] the bugs you find.
* Write and improve guides about the port.
* Fix [https://gitlab.alpinelinux.org/alpine/aports packages] that are buggy or don't work on RISC-V.
''This section is based on [https://irclogs.alpinelinux.org/%23alpine-riscv64-2025-10.log this] [[Alpine Linux:IRC|IRC]] conversation from 2025-10-01.''

[[Category:Riscv64]]

User:Aarch0x40

2026-03-29T06:39:17Z

Aarch0x40:

== Some things I'm helping out with ==
* [[Riscv64]]
* [[Riscv64 Redo]]
* [[Installing Alpine Linux on OrangePi RV2]]

Installing Alpine Linux on OrangePi RV2

2026-03-29T06:36:28Z

Aarch0x40:

Installing Alpine Linux on OrangePi RV2

2026-03-29T06:35:54Z

Aarch0x40:

Installing Alpine Linux on OrangePi RV2

2026-03-29T05:35:56Z

Aarch0x40:

Installing Alpine Linux on OrangePi RV2

2026-03-29T05:11:39Z

Aarch0x40:

Installing Alpine Linux on OrangePi RV2

2026-03-29T04:02:36Z

Aarch0x40: /* Setting up a workspace */

Installing Alpine Linux on OrangePi RV2

2026-03-29T04:01:11Z

Aarch0x40:

Riscv64 Redo

2026-03-29T03:43:54Z

Aarch0x40:

{{Draft}}
[[Main Page]] > [[:Category:Architectures|Architectures]] > Riscv64

riscv64 (RISC-V 64-bit) is one of the [[architecture|architectures]] that Alpine Linux supports. The first stable release was Alpine Linux 3.20. Standard ISO images are available since Alpine Linux 3.23. You can download it from the [https://alpinelinux.org/downloads/ Alpine Linux downloads] page.

RISC-V is an open source instruction set architecture (ISA) that was originally developed at UC Berkeley. It's currently maintained by [https://riscv.org/ RISC-V International]. Organizations are allowed to implement the RISC-V ISA with their own custom extensions. This results in their being some specificity to each implementation that makes it to market. Below you'll find links to articles which detail how to get Alpine Linux running on your board or VM.

== Alpine Linux on Specific RISC-V Implementations ==
 
{{Warning|The contributors to the Alpine Linux project are not responsible for any damage/loss experienced by using the following guides. The following articles are provided as a general reference to be adapted to your specific setup. It is assumed that the implementer will have the knowledge and ability to close the gap between what is described here and their specific setup.}}
* [[Riscv64|Running Alpine riscv64 in QEMU]]
* [[Installing Alpine Linux on OrangePi RV2]]

== Contribute ==
* Test out the port and [https://gitlab.alpinelinux.org/alpine/aports/-/issues/?label_name%5B%5D=arch%3Ariscv64 report] the bugs you find.
* Write and improve guides about the port.
* Fix [https://gitlab.alpinelinux.org/alpine/aports packages] that are buggy or don't work on RISC-V.
''This section is based on [https://irclogs.alpinelinux.org/%23alpine-riscv64-2025-10.log this] [[Alpine Linux:IRC|IRC]] conversation from 2025-10-01.''

[[Category:Riscv64]]

Installing Alpine Linux on OrangePi RV2

2026-03-29T03:43:09Z

Aarch0x40:

Installing Alpine Linux on OrangePi RV2

2026-03-29T03:18:01Z

Aarch0x40:

[[Main Page]] > [[:Category:Architectures|Architectures]] > [[Riscv64]] > Installing Alpine Linux on OrangePi RV2
 
{{Warning|The contributors to the Alpine Linux project are not responsible for any damage/loss experienced by using the following guide. This article is provided as a general reference to be adapted to your specific setup. It is assumed that the implementer will have the knowledge and ability to close the gap between what is described here and their specific setup.}}

== Known issues ==
 
{{Warning|The following are the issues that are known to exist between the result of this guide and the manufacturer provided image}}

* The WiFi is not functional
* Manufacturer tools are not included

[[Category:Riscv64]]

Installing Alpine Linux on OrangePi RV2

2026-03-29T03:07:30Z

Aarch0x40: