Skip to content

Homepage

Ahmad Hadidi

Commands below use these values. Click any highlighted value in a code block to change it. Saved in this browser only.

Container

This guide

Also uses your values: Template folder, Bridge, Gateway, CT disk storage, LAN proxy CTID, LAN proxy IP, Cloudflare tunnel CTID, Your domain, Your Access policy, Friend's Access policy, Friend's email

Your Homepage dashboard on Alpine 3.24 with Homepage v2.4.0.

Install

Host: prepare the config share, create CT

Proxmox host
mkdir -p /mnt/pve/evo/template_config/homepage
chmod 0777 /mnt/pve/evo/template_config/homepage
Proxmox host
{
read -rs -p "Root password for the new CT: " PW; echo
pct create \
103 \
/mnt/pve/evo/template/cache/alpine-3.24-default_20260714_amd64.tar.xz \
--hostname homepage \
--cores 4 \
--memory 2048 \
--net0 name=eth0,bridge=vmbr0,firewall=1,gw=192.168.0.1,ip=192.168.0.103/24,hwaddr=DE:AD:DE:AD:01:03,type=veth,ip6=dhcp \
--rootfs local-lvm:3 \
--mp0 /mnt/pve/evo/template_config/homepage,mp=/opt/homepage/config \
--unprivileged 1 \
--ignore-unpack-errors \
--ostype alpine \
--timezone Asia/Amman \
--password="$PW" \
--start 1
unset PW
}

Enter CT

Proxmox host
pct enter 103
In CT
# Request IP Address From Router
udhcpc -i eth0 -F $(hostname) -x hostname:$(hostname) -r $(hostname -i)

In CT: build

In CT
apk add tzdata nodejs npm git
ln -sf /usr/share/zoneinfo/Asia/Amman /etc/localtime
npm install -g pnpm
git clone --branch v2.4.0 --depth 1 https://github.com/gethomepage/homepage.git /root/homepage-src
cd /root/homepage-src
pnpm install --frozen-lockfile
NEXT_TELEMETRY_DISABLED=1 pnpm build

In CT: deploy the standalone app

In CT
cd /root/homepage-src
tar -C .next/standalone --exclude=./config -cf - . | tar -C /opt/homepage -xf -
mkdir -p /opt/homepage/.next
cp -a .next/static /opt/homepage/.next/static
cp -a public /opt/homepage/public

In CT: remove the build tools

In CT
cd /
rm -rf /root/homepage-src /root/.local/share/pnpm /root/.cache
npm uninstall -g pnpm
apk del npm git

In CT: service

In CT
addgroup -S homepage
adduser -S -D -H -h /opt/homepage -s /sbin/nologin -G homepage homepage
cat > /etc/init.d/homepage <<'EOF'
#!/sbin/openrc-run
name=homepage
description="Homepage dashboard"
supervisor=supervise-daemon
command=/usr/bin/env
command_args="NODE_ENV=production HOSTNAME=0.0.0.0 PORT=3000 HOMEPAGE_ALLOWED_HOSTS=192.168.0.103:3000,homepage.lan /usr/bin/node server.js"
command_user=homepage:homepage
directory=/opt/homepage
output_log=/var/log/homepage/output.log
error_log=/var/log/homepage/error.log
respawn_delay=5
respawn_max=0

depend() {
	need net localmount
	use dns logger netmount
}

start_pre() {
	checkpath -d -o homepage:homepage /var/log/homepage
}
EOF
chmod +x /etc/init.d/homepage
rc-update add homepage
service homepage start

Verify

In CT
sleep 5
wget -qO- http://127.0.0.1:3000/api/healthcheck; echo
wget -S -O /dev/null --header "Host: homepage.lan" http://127.0.0.1:3000/ 2>&1 | grep HTTP/
ls /opt/homepage/config

Shrink (optional)

Proxmox host
pct stop 103
vzdump 103 --mode stop --compress zstd --storage local
pct restore 103 /var/lib/vz/dump/vzdump-lxc-103-<TIMESTAMP>.tar.zst --rootfs local-lvm:1 --force
pct start 103

Expose config to Samba

Your browser
[template_config]
follow symlinks = yes
wide links = yes
browseable = yes
writeable = yes
path = /template_config
only guest=no
create mask= 0777
directory mask= 0777
public=yes
read only=no
force user=root

Let’s get started

In CT
apk add nano
cd /opt/homepage/config

# backup to blow up however we like
cp bookmarks.yaml bookmarks.bak
cp services.yaml services.bak
cp settings.yaml settings.bak
cp widgets.yaml widgets.bak

nano /opt/homepage/config/services.yaml

Go crazy CustomAPI - F1 Widget · gethomepage/homepage · Discussion #3412 · GitHub

Optional: reach it at homepage.lan

Needs the Nginx LAN proxy. Run this on the node that hosts the proxy.

Proxmox host
pct exec 101 -- add-lan-app homepage.lan 192.168.0.103 3000
MikroTik
/ip dns static add name=homepage.lan address=192.168.0.101

Optional: reach it through the Cloudflare tunnel

Needs the Cloudflared tunnel. On the node that hosts it:

Proxmox host
pct exec 102 -- add-cf-app homepage.hadidi.art 192.168.0.103 3000
pct exec 102 -- protect-cf-app homepage.hadidi.art "HDD"
# Share with a friend
pct exec 102 -- add-cf-policy "Friend" [email protected]
pct exec 102 -- protect-cf-app --add homepage.hadidi.art "Friend"

Ref

Update

Grow the disk (if shrunk)

Proxmox host
pct resize 103 rootfs 3G

Update Homepage

Check the new release’s Node requirement and HOMEPAGE_ALLOWED_HOSTS first.

In CT
VERSION=$(wget -qO- https://api.github.com/repos/gethomepage/homepage/releases/latest | tr ',' '\n' | grep '"tag_name"' | cut -d'"' -f4)
apk add nodejs npm git
npm install -g pnpm
git clone --branch "$VERSION" --depth 1 https://github.com/gethomepage/homepage.git /root/homepage-src
cd /root/homepage-src
pnpm install --frozen-lockfile
NEXT_TELEMETRY_DISABLED=1 pnpm build
service homepage stop
find /opt/homepage -mindepth 1 -maxdepth 1 ! -name config -exec rm -rf {} +
tar -C .next/standalone --exclude=./config -cf - . | tar -C /opt/homepage -xf -
mkdir -p /opt/homepage/.next
cp -a .next/static /opt/homepage/.next/static
cp -a public /opt/homepage/public
cd /
rm -rf /root/homepage-src /root/.local/share/pnpm /root/.cache
npm uninstall -g pnpm
apk del npm git
service homepage start

Remove

Remove from the LAN proxy

Only if you added it to the Nginx LAN proxy. Run this on the node that hosts the proxy.

Proxmox host
pct exec 101 -- sed -i '/^ *homepage\.lan /d' /etc/nginx/http.d/map-backends.conf
pct exec 101 -- nginx -s reload
MikroTik
/ip dns static remove [find name=homepage.lan]

Remove from the Cloudflare tunnel

Only if you added it to the Cloudflared tunnel. Run this on the node that hosts the tunnel.

Proxmox host
pct exec 102 -- del-cf-app homepage.hadidi.art

Delete the CT

Proxmox host
pct stop 103
pct destroy 103