Tutorials and Howtos

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 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 Discussion.

Desktop

Alpine Linux is a general purpose Linux distribution designed for power users. It is built to be small and resource efficient. If you feel the defaults are too lightweight for desktop use, it is easy to get most of the regular stuff working and use Alpine Linux as a daily driver by following this guide.

Tip: Help improve Alpine Linux wiki!

• If the instructions on a section/page are correct, add/update the Verified template.
• If something isn't correct, or is incomplete, add the Accuracy template to the relevant section/page.

You will have to figure out the correct solution, or ask for it in the community.

And then carefully edit the wiki page, just as those before who did it for you.

Prerequisites

• Alpine Linux installed in system disk mode.
• Internet connectivity, unless the packages have been pre-fetched into a local cache.
• Install appropriate Graphics driver drivers for your hardware. Without graphics drivers, errors are likely to occur when starting your desktop.
• A non-root user account with appropriate groups for desktop usage.
• The community repository must be enabled.
• Set up eudev.
• Install and enable D-Bus. Without D-Bus, icons and keyboard shortcuts may be missing.

Once the above prerequisites are met, install any desktop of choice from the list of supported Desktop environments and Window managers either manually or using setup-desktop script.

Tip: Except for the first three Prerequisites, all the others are automatically handled, if setup-desktop script is used.

Basics

• Learn the alpine package keeper basics or refer wiki page.
• Install some fonts to make your desktop look better.
• Install the necessary File management packages for automounting of removable storage and browsing of network shares that works seamlessly with file associations.
• Setup a sound server to manage your audio and configure your Bluetooth, if you have one.
• Configure Power management so that your computer switches to a low-power state when inactive or when laptop lid is closed.
• Configure your printer. If needed, use mDNS for discovery of printers.
• Enable documentation, so man pages are available locally. For online version refer https://manned.org
• Graphical tools to manage official packages, Flatpaks and ways to run glibc binaries can be found in Software management page.

Desktop security

• If you have a fingerprint sensor,refer Fingerprint authentication page.
• Install CPU Microcode updates to mitigate processor design bugs.
• Regularly check and apply updates to keep your system secure.
• Upgrade your OS whenever a new stable version of Alpine Linux is released
• Secure your system by installing a firewall software like Uncomplicated Firewall or nftables.
• Install a sandboxing application like AppArmor or Bubblewrap. AppArmor is more convenient but has less control than Bubblewrap. Bubblewrap is harder to work with but has more control than AppArmor.
• Enable UEFI Secure Boot, if UEFI is available.
• Refer to security section for additional security options.

Advanced

• Learn basics of openrc, the alpine Linux init system or refer Open rc wiki.
• If you want the rolling release version of Alpine Linux, enable the Edge repository.
• Explore the testing repository, as it provides a lot more applications.

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
  • 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 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
• 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
• List of supported Desktop environments and Window managers

Diskless

• 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

ARM

• Alpine on ARM

Raspberry Pi

• Raspberry Pi main page
• Raspberry Pi - Bluetooth Speaker
• Raspberry Pi - Router with VPN
• Raspberry Pi - Router with VPN (IPv6)
• Raspberry Pi - Sys mode install
• Raspberry Pi - Sys mode install - LVM on LUKS
• 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 - Wireless router (Setting up a firewalled, Wireless AP with wired network on a Pi Zero W)
• RPI Video Receiver

IBM Z (IBM z Systems)

• s390x - Installation

PowerPC

• Powerpc64le - Installation

Security

• Desktop security lists steps for securing Alpine Linux desktops
• Setting up a laptop page has detailed guidelines to configure a secured laptop
• Secure Alpine Linux using Security Technical Implementation Guides (STIGs)
• 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

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

• nfs-server
• samba-server (standard file sharing)
• samba-ad-dc (Active Directory compatible domain controller)

Firewall

• 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 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‎‎
• Nginx
  • Nginx as reverse proxy with acme (letsencrypt)
  • Nginx with PHP
• Squid Proxy
  • Obtaining user information via SNMP (Using squark-auth-snmp as a Squid authentication helper)
  • 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 + 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)
• 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 - the professional complete manager (Monitor and track the status of network services and hardware)
• ZoneMinder video camera security and surveillance

Remote Administration

• ACF
  • ACF - changing passwords
  • Generating SSL certs with 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)
  • 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 on Alpine Linux
• Setting up Zaptel/Asterisk on Alpine
• Kamailio (SIP Server, formerly OpenSER)

VPN

• Freeradius Active Directory Integration
• GNUnet
• IGMPproxy
• OpenVPN server (Allowing single users or devices to remotely connect to your network)
• OpenVSwitch
• Tor
• Using Alpine on Windows domain with IPSEC isolation
• Wireguard
• Vpnc

Other Servers

• apcupsd (UPS Monitoring with apcupsd)
• 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 (UPS Monitoring with Network UPS Tools)
• Odoo
• OpenLDAP (Installing and configuring the Alpine package for OpenLDAP)
• 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)
• Trac (Enhanced wiki and issue tracking system for software development projects)
• Ansible (Configuration management)
• Oracle Java (installation)

Storage

• Manual partitioning
• DRBD: Disk Replication
• Filesystems
  • Burning ISOs
• iSCSI Setup
  • iSCSI Raid and Clustered File Systems
  • iSCSI Target (TCM)/LinuxIO (LIO)
  • User space iSCSI Target (tgt)
• LVM Setup
  • LVM on GPT-labeled disks
  • 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

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
  • 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
• 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
• Setting up A Network Monitoring and Inventory System (Nagios + OpenAudit and related components)
• Streaming Security Camera Video with VLC
• Install Alpine on a btrfs filesystem with refind as boot manager
• How to Compile a software from source in Alpine Linux
• Alpine Linux tutorials - Dr Murphy, Computing Science Associate Professor
• Michael's base installation procedure
• Michael's cwm desktop (minimal)
• Michael's Sway desktop (minimal)
• Sway customization guide (Tutorial re Sway config file basics)
• Using Distrobox For VR Gaming