docs/getting_started.md

   1 ## Using Docker
   2
   3 The fastest and recommended way to get your Homer instance up and running is
   4 with Docker. The Docker image comes with a web server built-in so that all you
   5 need to worry about is your config file.
   6
   7 Internally, the Docker image looks for the assets in the `/www/assets` directory
   8 so you can bind a volume from your host machine to that directory in order to
   9 modify and persist the configuration files. The web server serves the dashboard
  10 on port 8080, but using a port binding will let you expose that to whatever
  11 external port you like.
  12
  13 ### docker
  14
  15 To launch container:
  16
  17 ```sh
  18 docker run -d \
  19   -p 8080:8080 \
  20   -v </your/local/assets>:/www/assets \
  21   --restart=always \
  22   b4bz/homer:latest
  23 ```
  24
  25 Use `UID` and/or `GID` env var to change the assets owner:
  26
  27 ```sh
  28 docker run -d \
  29   -p 8080:8080 \
  30   -v </your/local/assets>:/www/assets \
  31   -e "UID=1000" -e "GID=1000" \
  32   --restart=always \
  33   b4bz/homer:latest
  34 ```
  35
  36 ### docker-compose
  37
  38 It is recommended to use docker-compose to manage your Docker containers, and
  39 below you can find a simple compose yaml file. Copy the contents into a
  40 `docker-compose.yaml` and modify the volume binding to your desired directory to
  41 get started:
  42
  43 ```yaml
  44 version: '3.3'
  45 services:
  46   homer:
  47     restart: always
  48     volumes:
  49       - /your/local/assets:/www/assets
  50     ports:
  51       - 8080:8080
  52     image: b4bz/homer
  53 ```
  54
  55 To launch container:
  56
  57 ```sh
  58 cd /path/to/docker-compose.yml
  59 docker-compose up -d
  60 ```
  61
  62 Use `UID` and/or `GID` env var to change the assets owner:
  63
  64 ```yaml
  65 version: '3.3'
  66 services:
  67   homer:
  68     restart: always
  69     volumes:
  70       - /your/local/assets:/www/assets
  71     ports:
  72       - 8080:8080
  73     environment:
  74       - UID=1000
  75       - GID=1000
  76     image: b4bz/homer
  77 ```
  78
  79 ## Shipping your own web server
  80
  81 ### Prebuilt release tarball
  82
  83 Download and extract the latest release (`homer.zip`) from the [release page](https://github.com/bastienwirtz/homer/releases), rename the `assets/config.yml.dist` file to `assets/config.yml`, and put it behind a web server.
  84
  85 ```sh
  86 wget https://github.com/bastienwirtz/homer/releases/latest/download/homer.zip
  87 unzip homer.zip
  88 cd homer
  89 cp assets/config.yml.dist assets/config.yml
  90 npx serve # or python -m http.server 8010 or apache, nginx ...
  91 ```
  92
  93 ### Building from source
  94
  95 ```sh
  96 # Using yarn (recommended)
  97 yarn install
  98 yarn build
  99
 100 # **OR** Using npm
 101 npm install
 102 npm run build
 103 ```
 104
 105 Then your dashboard is ready to use in the `/dist` directory.