Bare Metal Installation

Overview

Running Homarr directly on your system (bare metal) gives you more control over the installation and can be useful for development, testing, or environments where Docker is not available. This method requires manual setup of all dependencies.

Bare metal installation is more complex than Docker and requires manual management of Node.js, databases, and dependencies. Docker is recommended for most users.

Prerequisites

System Requirements

Operating System: Linux, macOS, or Windows (with WSL2)
CPU: 2+ cores recommended
RAM: 1 GB minimum, 2 GB+ recommended
Storage: 2 GB for application and dependencies

Required Software

Node.js 24.14.0+

Homarr requires Node.js 24.14.0 or higher:

curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt-get install -y nodejs

Verify installation:

node --version  # Should output v24.14.0 or higher

pnpm 10.30.3+

Homarr uses pnpm as its package manager:

npm install -g [email protected]

Verify installation:

pnpm --version  # Should output 10.30.3 or higher

Build Tools

Install build tools for native dependencies:

sudo apt-get install -y build-essential python3 git

Database (Optional)

Install your preferred database:

# SQLite comes with Node.js better-sqlite3
# No additional installation needed

Redis (Optional)

Install Redis for caching:

sudo apt-get install -y redis-server
sudo systemctl start redis

Redis is optional. Homarr includes an embedded Redis instance that starts automatically.

Installation Steps

Clone the Repository

git clone https://github.com/homarr-labs/homarr.git
cd homarr

Or download a specific release:

wget https://github.com/homarr-labs/homarr/archive/refs/tags/v1.54.0.tar.gz
tar -xzf v1.54.0.tar.gz
cd homarr-1.54.0

Install Dependencies

Install all project dependencies:

pnpm install --frozen-lockfile

This will install dependencies for all packages in the monorepo. It may take 5-10 minutes depending on your system.

Configure Environment

Create your environment configuration:

cp .env.example .env

Edit .env with your settings:

.env

# Required: Generate with openssl rand -hex 32
SECRET_ENCRYPTION_KEY=0000000000000000000000000000000000000000000000000000000000000000

# Database Configuration
DB_DRIVER=better-sqlite3
DB_URL=/path/to/your/homarr/data/db/db.sqlite

# Or use MySQL
# DB_DRIVER=mysql2
# DB_HOST=localhost
# DB_PORT=3306
# DB_USER=homarr
# DB_PASSWORD=your-password
# DB_NAME=homarrdb

# Or use PostgreSQL
# DB_DRIVER=node-postgres
# DB_URL=postgres://homarr:password@localhost:5432/homarrdb

# Logging
LOG_LEVEL=info

# Authentication
AUTH_PROVIDERS=credentials

# Disable telemetry
TURBO_TELEMETRY_DISABLED=1

Generate a secure SECRET_ENCRYPTION_KEY:

openssl rand -hex 32

Save this key securely - you’ll need it to decrypt integration credentials.

Create Data Directories

mkdir -p /path/to/your/homarr/data/db
mkdir -p /path/to/your/homarr/data/redis
mkdir -p /path/to/your/homarr/data/trusted-certificates

Build the Application

Build all packages and applications:

pnpm build

This compiles TypeScript, bundles Next.js, and prepares all services. Build time: 5-15 minutes.

Run Database Migrations

Initialize the database:

pnpm db:migration:sqlite:run

Start Homarr

Start all services:

pnpm start

This starts:

Next.js server on port 3000
WebSocket server on port 3001
Background task processor
Embedded Redis (if not using external)

The first start may take 30-60 seconds as Next.js optimizes the application.

Accessing Homarr

Once started, access Homarr at:

Local: http://localhost:3000
Network: http://YOUR_SERVER_IP:3000

Unlike the Docker image which uses Nginx on port 7575, bare metal installations use Next.js directly on port 3000.

Development Mode

For development with hot-reload:

# Start development servers for all apps
pnpm dev

This starts:

Next.js dev server on port 3000 (with hot reload)
WebSocket dev server on port 3001
Task processor with auto-restart

Production Setup

Using PM2 Process Manager

PM2 ensures Homarr runs continuously and restarts on crashes:

Install PM2

npm install -g pm2

Create PM2 Ecosystem File

Create ecosystem.config.js:

ecosystem.config.js

module.exports = {
  apps: [
    {
      name: 'homarr-nextjs',
      cwd: './apps/nextjs',
      script: 'node_modules/.bin/next',
      args: 'start',
      instances: 1,
      exec_mode: 'fork',
      env: {
        NODE_ENV: 'production',
        PORT: 3000
      }
    },
    {
      name: 'homarr-websocket',
      cwd: './apps/websocket',
      script: './wssServer.cjs',
      instances: 1,
      exec_mode: 'fork',
      env: {
        NODE_ENV: 'production'
      }
    },
    {
      name: 'homarr-tasks',
      cwd: './apps/tasks',
      script: './tasks.cjs',
      instances: 1,
      exec_mode: 'fork',
      env: {
        NODE_ENV: 'production'
      }
    }
  ]
}

Start with PM2

# Start all services
pm2 start ecosystem.config.js

# Save process list
pm2 save

# Setup auto-start on boot
pm2 startup

Manage Services

# View status
pm2 status

# View logs
pm2 logs

# Restart all
pm2 restart all

# Stop all
pm2 stop all

# Monitor resources
pm2 monit

Using Systemd (Linux)

Create systemd service files for automatic startup:

[Unit]
Description=Homarr Next.js Server
After=network.target

[Service]
Type=simple
User=homarr
WorkingDirectory=/opt/homarr/apps/nextjs
Environment="NODE_ENV=production"
Environment="PORT=3000"
EnvironmentFile=/opt/homarr/.env
ExecStart=/usr/bin/node /opt/homarr/apps/nextjs/server.js
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and start services:

sudo systemctl daemon-reload
sudo systemctl enable homarr-nextjs homarr-websocket homarr-tasks
sudo systemctl start homarr-nextjs homarr-websocket homarr-tasks

# Check status
sudo systemctl status homarr-*

Reverse Proxy Setup

Nginx

Create /etc/nginx/sites-available/homarr:

server {
    listen 80;
    server_name homarr.example.com;

    client_max_body_size 32M;

    # WebSocket support
    location /websockets {
        proxy_pass http://localhost:3001;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # Main application
    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Enable and reload:

sudo ln -s /etc/nginx/sites-available/homarr /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Caddy

Add to Caddyfile:

homarr.example.com {
    reverse_proxy /websockets localhost:3001
    reverse_proxy localhost:3000
}

Reload Caddy:

sudo caddy reload

Updating Homarr

Backup your data

# Backup database
cp /path/to/data/db/db.sqlite /path/to/backups/db-$(date +%Y%m%d).sqlite

# Backup environment file
cp .env .env.backup

Stop services

pm2 stop all

Update code

git fetch --all
git checkout v1.54.0  # Or latest version

Update dependencies

pnpm install --frozen-lockfile

Rebuild application

pnpm build

Run migrations

pnpm db:migration:sqlite:run  # Or mysql/postgresql

Restart services

pm2 restart all

Troubleshooting

Build Errors

If build fails:

# Clean build artifacts
pnpm clean
pnpm clean:workspaces

# Remove node_modules
rm -rf node_modules
rm -rf apps/*/node_modules
rm -rf packages/*/node_modules

# Reinstall and rebuild
pnpm install --frozen-lockfile
pnpm build

Node.js Version Issues

Ensure correct Node.js version:

node --version  # Should be v24.14.0+

# If using nvm
nvm use 24.14.0

Port Already in Use

Check what’s using the port:

# Check port 3000
lsof -i :3000

# Or using netstat
netstat -tulpn | grep 3000

# Kill process
kill -9 <PID>

Database Connection Errors

Verify database configuration:

# Test MySQL connection
mysql -u homarr -p -h localhost homarrdb

# Test PostgreSQL connection
psql -U homarr -h localhost homarrdb

# Check SQLite file permissions
ls -la /path/to/data/db/db.sqlite

Performance Optimization

Enable Production Mode

Always run with NODE_ENV=production:

export NODE_ENV=production
pnpm start

Optimize Next.js

In apps/nextjs/next.config.ts, ensure:

export default {
  output: 'standalone',
  compress: true,
  // Add more optimizations as needed
}

Use External Redis

For better performance:

.env

REDIS_IS_EXTERNAL=true
REDIS_HOST=localhost
REDIS_PORT=6379

Best Practices

Use a dedicated user - Don’t run as root
Set up firewall rules - Only expose necessary ports
Enable automatic updates - Keep Node.js and dependencies current
Monitor logs - Use PM2 or systemd logging
Regular backups - Automate database and file backups
Use external databases - MySQL or PostgreSQL for production
Set resource limits - Use ulimit to prevent resource exhaustion
Use process managers - PM2 or systemd for automatic restarts
Enable HTTPS - Use reverse proxy with SSL/TLS
Monitor performance - Use Node.js profiling tools

Next Steps

Configuration Guide

Configure Homarr for your environment

Database Setup

Set up MySQL or PostgreSQL

Integrations

Connect your self-hosted services

Troubleshooting

Common installation issues

Get Started

Core Features

Configuration

Integrations

Guides

Bare Metal Installation

Overview

Prerequisites

System Requirements

Required Software

Installation Steps

Accessing Homarr

Development Mode

Production Setup

Using PM2 Process Manager

Using Systemd (Linux)

Reverse Proxy Setup

Nginx

Caddy

Updating Homarr

Troubleshooting

Build Errors

Node.js Version Issues

Port Already in Use

Database Connection Errors

Performance Optimization

Enable Production Mode

Optimize Next.js

Use External Redis

Best Practices

Next Steps

Configuration Guide

Database Setup

Integrations

Troubleshooting

Build docs developers (and LLMs) love

Get Started

Core Features

Configuration

Integrations

Guides

​Overview

​Prerequisites

​System Requirements

​Required Software

​Installation Steps

​Accessing Homarr

​Development Mode

​Production Setup

​Using PM2 Process Manager

​Using Systemd (Linux)

​Reverse Proxy Setup

​Nginx

​Caddy

​Updating Homarr

​Troubleshooting

​Build Errors

​Node.js Version Issues

​Port Already in Use

​Database Connection Errors

​Performance Optimization

​Enable Production Mode

​Optimize Next.js

​Use External Redis

​Best Practices

​Next Steps

Configuration Guide

Database Setup

Integrations

Troubleshooting

Build docs developers (and LLMs) love

Overview

Prerequisites

System Requirements

Required Software

Installation Steps

Accessing Homarr

Development Mode

Production Setup

Using PM2 Process Manager

Using Systemd (Linux)

Reverse Proxy Setup

Nginx

Caddy

Updating Homarr

Troubleshooting

Build Errors

Node.js Version Issues

Port Already in Use

Database Connection Errors

Performance Optimization

Enable Production Mode

Optimize Next.js

Use External Redis

Best Practices

Next Steps