🚀 Installation

Homarr can be installed in many ways. For most users, Installation using Docker will be sufficient and the easiest.

Configuration

• Environment variables can be used to configure your Homarr deployment.

Environment Variable	Description	Examples
BASE_URL	Allows you to change the base URL you use to access Homarr	homarr.example.com
TZ	Allows you to set the time zone	Asia/Jerusalem
PASSWORD	Allows you to set a password for Password protection	-
PORT	Allows you to change the default port Homarr uses to deploy	1234

Installing

Docker

Docker is a free Software that isolates Homarr using containers. Using Docker, you can run Homarr on any supported plattform (including Windows and Raspberry Pi), easily.

Prerequisites

• Docker

To install Homarr using Docker, simply run the following command.

docker run  \
  --name homarr \
  --restart unless-stopped \
  -p 7575:7575 \
  -v <your-path>/homarr/configs:/app/data/configs \
  -v <your-path>/homarr/icons:/app/public/icons \
  -d ghcr.io/ajnart/homarr:latest

note

Docker will mount the configuration files and icons to your host machine. Please make sure to replace <your-path> from the docker run command with your desired storage location. The path must be absolute.

Updating

To update Homarr, you must remove your container first. Make sure that you've mounted your data and that you have access to it, so your configuration doesn't get lost.

1. Run docker rm homarr to remove the container.
2. Pull the latest Homarr image docker pull ghcr.io/ajnart/homarr:latest.
3. Re-run the command you used to install Homarr.

This process can get tideous, if you update frequently. Thus, we recommend the installation using docker-compose for more experienced users.

Docker Compose

Prerequisites

• Docker Compose

To install Homarr using Docker Compose, simply create a file called docker-compose.yml and paste the following code into it.

docker-compose.yml

version: '3'
#---------------------------------------------------------------------#
#     Homarr - A simple, yet powerful dashboard for your server.     #
#---------------------------------------------------------------------#
services:
  homarr:
    container_name: homarr
    image: ghcr.io/ajnart/homarr:latest
    restart: unless-stopped
    environment: # The following environment variables are optional. Please remove the '#' to use one.
      # - BASE_URL=
      # - TZ=
      # - PASSWORD=
      # - PORT=
    volumes:
      - <your-path>/configs:/app/data/configs
      - <your-path>/icons:/app/public/icons
    ports:
      - '7575:7575'

Then, run docker-compose up -d in the same directory. This will start the Homarr container in the background.

Updating

To update Homarr using Docker Compose, simply pull the latest image and restart the container.

1. Run docker pull ghcr.io/ajnart/homarr:latest to pull the latest image.
2. Re-run docker-compose up -d or re-deploy the stack in Portainer.

Portainer Stacks

Prerequisites

• Portainer Stacks

To install Homarr using Portainer Stacks, simply create a new stack and paste the following code into it.

docker-compose.yml

version: '3'
#---------------------------------------------------------------------#
#     Homarr - A simple, yet powerful dashboard for your server.     #
#---------------------------------------------------------------------#
services:
  homarr:
    container_name: homarr
    image: ghcr.io/ajnart/homarr:latest
    restart: unless-stopped
    environment: # The following environment variables are optional. Please remove the '#' to use one.
      # - BASE_URL=
      # - TZ=
      # - PASSWORD=
      # - PORT=
    volumes:
      - <your-path>/configs:/app/data/configs
      - <your-path>/icons:/app/public/icons
    ports:
      - '7575:7575'

note

Portainer will mount the configuration files and icons to your host machine. Please make sure to replace <your-path> from the docker run command with your desired storage location. The path must be absolute.

Then, click on Deploy the stack and wait until the container has started.

Updating

To update Homarr using Portainer Stacks, simply pull the latest image and restart the container.

1. Run docker pull ghcr.io/ajnart/homarr:latest to pull the latest image.
2. Re-run docker-compose up -d or re-deploy the stack in Portainer.

tip

If you're unsure how to create a stack, checkout the Portainer Stacks Documentation.

Unraid

You can install Homarr directly from your Unraid Dashboard, no terminal required.

Prerequisites

• Unraid
• Community Apps

Install the Community Apps Plugin

Open Installation Guide

tip

Don't know whether you have the plugin installed or not? Search for this tab in the navigation:

Installing

After you've installed the Community Apps Plugin, you can install Homarr from the Unraid Dashboard.

1. Navigate to the tab "Apps".
2. Search for "Homarr" and click on the result.
3. Click on "Install" and adjust the settings to your liking.

After you've installed Homarr, you can find it under the tab "Docker".

---

tip

Want to update all your containers automatically? Checkout Watchtower a service which will automatically update your containers on a set interval.

docker-compose.yml

version: "3"
services:
  watchtower:
    image: containrrr/watchtower:latest
    container_name: watchtower
    environment:
      - TZ=Asia/Jerusalem
      - WATCHTOWER_CLEANUP=true
      - WATCHTOWER_SCHEDULE=0 0 12 * * *
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /etc/localtime:/etc/localtime
    restart: unless-stopped

---

Building from source

caution

Installing Homarr from source is not recommended and only intended for developers and contributers, please use the Docker installation method instead.

Yarn Package Manager

1. Clone the Repository using git clone https://github.com/ajnart/homarr.git
2. Enter the created directory using cd homarr
3. Install all dependencies using yarn install
4. Build the source using yarn build
5. Start the NextJS web server using yarn start
6. Alternatively, use yarn dev to run a live development server.

NPM Package Manager

1. Clone the Repository using git clone https://github.com/ajnart/homarr.git
2. Enter the created directory using cd homarr
3. Install all dependencies using npm install
4. Build the source using npm build
5. Start the NextJS web server using npm start
6. Alternatively, use npm run dev to run a live development server.

---

Troubleshooting

Having trouble installing Homarr on your system? Check out our FAQ and Known Issues. If you are still running into issues, please contact us in our Discord server.