Posted on 7 Comments

LXD Dashboard – Installing from source in Alpine Linux

Launching an LXC based Alpine container

This how-to guide will take you through the installation steps to run the LXD dashboard in an LXC container on your system. This guide will assume that your system already has LXD installed and configured.

Start by launching a new instance using the Alpine 3.14 image. To launch the new instance and name it lxd-dashboard use the following command:

lxc launch images:alpine/3.14 lxd-dashboard

This will create a base container to use to install the LXD dashboard. Once the command finishes the container should be running. Now it is time to connect into the container and setup the software. Use the following command to obtain a shell connection to the instance, use the exit command at anytime to leave the shell:

lxc exec lxd-dashboard /bin/sh

Install Nginx and PHP

The following commands will now be run inside the lxd-dashboard container. The installation guide uses Nginx and PHP for the webserver platform and SQLite as a database. To install these packages use the following command:

apk update && apk add nginx php php-fpm php-curl sqlite php-sqlite3 php7-session php7-pdo php7-pdo_sqlite php7-json php7-openssl 

Setting up the LXD Dashboard

Using wget, the source code for the LXD dashboard can be downloaded from the GitHub repository. For this guide the v3.4.0 release will be used. Check for newer versions on the GitHub page and replace the version number with the latest. To download and extract the source code use the following two commands:

tar -xzf v3.4.0.tar.gz

A few web server files will need to moved into place for the web pages as well as the NGINX configuration. To copy these files use the following commands, making sure to change the version number to what was downloaded:

cp -a lxd-dashboard-3.4.0/default /etc/nginx/http.d/default.conf
mkdir -p /www
cp -a lxd-dashboard-3.4.0/lxd-dashboard /www/

The default.conf file used for Nginx needs slighly modified to work in Alpine Linux.

vi /etc/nginx/http.d/default.conf

Modify the default.conf file to read as follows, paying close attention to the text in red:

server {
	listen 80 default_server;
	listen [::]:80 default_server;
	root /www/lxd-dashboard;
	index index.php index.html;
	server_name _;

	location / {
		try_files $uri $uri/ =404;
	location ~ \.php$ {
    	fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    	include fastcgi_params;
    	include fastcgi.conf;

The default user:group assigned to php-fpm is nobody:nobody. This will need to be changed to the user and group used by the webserver, nginx:www-data. Edit the /etc/php7/php-fpm.d/www.conf file and change the user and group assignment.

vi /etc/php7/php-fpm.d/www.conf

There are three main directories that LXDWARE uses to store persistent information for the application. You will need to create these directories and then assign appropriate ownership to the web server. To create the directories use the following commands:

mkdir -p /var/lxdware/data/sqlite
mkdir -p /var/lxdware/data/lxd
mkdir -p /var/lxdware/backups

The /www/lxd-dashboard/ directory, the /var/lxdware/ directory, and the contents within them all need to be owned by the web server user. Although the /etc/nginx/nginx.conf file lists nginx as the user, when configuring the LXD Dashboard, the nobody user was being used by the webserver. To set the proper permissions run the following commands:

chown -R nginx:www-data /var/lxdware/
chown -R nginx:www-data /www/

Starting and Enabling the Nginx and PHP services

The NGINX web server and PHP will both need to be started. To start the web server run the following commands:

service nginx start
service php-fpm7 start

To enable both services to start automatically when the server boots use the following two commands:

rc-update add nginx default
rc-update add php-fpm7 default

Congratulations! The container is now setup with the LXD dashboard software. Exit from the shell terminal and return to your LXD host server by using the command:


Open a web browser and access the LXD dashboard by entering in the IP address of the instance. Use the lxc list command to view a list of the containers and their IP addresses on your LXD server.

Known Issues with Alpine

The php-fpm application in Alpine Linux is preventing the LXD Dashboard from exporting instance backups from the LXD server to the to /var/lxdware/backups/… directory.

7 thoughts on “LXD Dashboard – Installing from source in Alpine Linux

  1. Updated this guide to use the current 3.4.0 version of LXD Dashboard

  2. Hello Matthew,

    do you know, WHY there the php-fpm application in Alpine Linux prevents your *amazing* LXD Dashboard from exporting instance backups to /var/lxdware/backups – directory? I would like to fix that, I am using your LXD Dashboard in Alpine..

    keep up the great work,
    Ingo Baab

    1. Hello Ingo,
      I am not sure yet why exporting is not working for Alpine. I remember trying to see if it would working giving the directory 777 permissions, but I don’t think that worked either. I can take a look again and investigate to see what might be going on.

  3. Alpine packages for php8:

    apk add nginx php php-fpm php-curl sqlite php-sqlite3 php8-session php8-pdo php8-pdo_sqlite php8-openssl

    (in php8 json is a core module)

  4. Notes for SSL login:

    I use xca for 4096 bit self signed certs (so I can import the self signed CA into my browsers)

    The SSL folder can be root owned & readable only by root as certs are read before nginx drops privileges.

    mkdir -p /etc/nginx/ssl
    chmod 750 /etc/nginx/ssl
    chown root:root /etc/nginx/ssl

    # & copy your SSL certificate / private key into /etc/nginx/ssl
    # nowadays you should be configuring web services to use TLS 1.2 only
    # /etc/nginx/http.d/default.conf

    server {
    listen 443 ssl;
    listen [::]:443 ssl;
    ssl_certificate /etc/nginx/ssl/lxdware.crt;
    ssl_certificate_key /etc/nginx/ssl/lxdware.key;
    ssl_protocols TLSv1.2;
    ssl_ciphers HIGH:!aNULL:!MD5;

    root /www/lxd-dashboard;
    index index.php index.html;
    server_name _;

    location / {
    try_files $uri $uri/ =404;

    location ~ \.php$ {
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    include fastcgi_params;
    include fastcgi.conf;

  5. Backups in Alpine Linux with php8 using the above settings work without any problems. I downloaded & deleted a container backup successfully (I didn’t test an LXD vm as I don’t use them).

    I connect my home machine to my remote LXD nodes with Wireguard so the LXD port is not exposed to the internet. I tested with an Alpine LXD container running LXDWARE in my home LXD system & added the remote hosts with my local LXD server as the “External Address” / “External Port”. I used the Wireguard private subnet ip’s for each host setting.

    Thank you for making a great LXD Control Panel ;o)

    I’ve written a console app for Distrobuilder for building custom LXD images (with or without cloud-init) – I’ve used it so far for building various images including Gitlab / k3s nodes (which install on first boot). It just needs a little work to package into a Python module. I was using Packer with Ansible but it broke a few months ago so I wrote something to give the same functionality. I create a base image for each distribution with my shell settings etc & use the base image to build images for each specific app / use case. I tend to use cloud-init with Ubuntu images & no cloud-init with Alpine as you can edit the image template to enable services.

    1. Thank you Stuart. This is wonderful information on setting up the dashboard for Alpine users. I will test it and update the post.

Leave a Reply

Your email address will not be published. Required fields are marked *