[Windows] Include service installation instructions (#398)
* Include Windows Service Installation method Signed-off-by: Angelos Fountoulakis <agf@wired-net.gr> (github: AngelosF) * Small formatting corrections Signed-off-by: Angelos Fountoulakis <agf@wired-net.gr> (github: AngelosF) * More formatting changes... Signed-off-by: Angelos Fountoulakis <agf@wired-net.gr> (github: AngelosF) * Images for Windows Installation Signed-off-by: Angelos Fountoulakis <agf@wired-net.gr> (github: AngelosF) * 1 more image Signed-off-by: Angelos Fountoulakis <agf@wired-net.gr> (github: AngelosF) * More formatting changes (and images) Signed-off-by: Angelos Fountoulakis <agf@wired-net.gr> (github: AngelosF) * Change wrapper.log destination Signed-off-by: Angelos Fountoulakis <agf@wired-net.gr> (github: AngelosF) * Add more SSH Client options Signed-off-by: Angelos Fountoulakis agf@wired-net.gr (github: AngelosF) * Added OPENHAB_* (as in oh2_dir_layout) Signed-off-by: Angelos Fountoulakis agf@wired-net.gr (github: AngelosF) * Downloadable Wrapper config file Unfortunately, the auto generated wrapper.conf is "broken" and we need to make significant changes to it for the installation of the Windows service to work. (temporarily) We can provide two methods/options to fix this issue: (1) download the attached template and overwrite existing or (2) manually edit existing Signed-off-by: Angelos Fountoulakis agf@wired-net.gr (github: AngelosF) * Updated following @ThomDietrich's review Hopefully it's better now... (it's not perfect.. I know :)) Signed-off-by: Angelos Fountoulakis agf@wired-net.gr (github: AngelosF) * FIx formatting issues Signed-off-by: Thomas Dietrich <thomas.dietrich@tu-ilmenau.de> (github: ThomDietrich) * Improve numbered list indention Signed-off-by: Thomas Dietrich <thomas.dietrich@tu-ilmenau.de> (github: ThomDietrich) * New update [!] Rephrased installation step 4 for the windows service [-] Removed the "download wrapper.conf" part [!] added some empty lines between text and images [!] changed a bit the wrapper.conf content Signed-off-by: Angelos Fountoulakis agf@wired-net.gr (github: AngelosF) * Remove file `installation/openHAB2-wrapper.conf` Signed-off-by: Angelos Fountoulakis agf@wired-net.gr (github: AngelosF) * Change Windows Service Log destinations [!] All log destinations (`openhab.log, event.log & wrapper.log`) set to `C:\openHAB2\userdata\logs` (instead of `C:\openHAB2\logs`) as specified in the File Locations section Signed-off-by: Angelos Fountoulakis agf@wired-net.gr (github: AngelosF) * Added first image (JAVA_HOME.png) Signed-off-by: Angelos Fountoulakis agf@wired-net.gr (github: AngelosF) * Changed Image path for Java_Home.png Signed-off-by: Angelos Fountoulakis agf@wired-net.gr (github: AngelosF) * Indent SSH instructions Signed-off-by: Thomas Dietrich <thomas.dietrich@tu-ilmenau.de> (github: ThomDietrich) * Add TOC Signed-off-by: Thomas Dietrich <thomas.dietrich@tu-ilmenau.de> (github: ThomDietrich)pull/406/head
Angelos Fountoulakis
Thomas Dietrich
parent
47e4f3121b
commit
2fa83abacc
Binary file not shown.
|
After Width: | Height: | Size: 27 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 21 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 11 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 72 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 75 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 50 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 61 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 107 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 195 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 51 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 35 KiB |
|
|
@ -9,17 +9,25 @@ title: Windows
|
|||
|
||||
The following instructions will guide you through the process of setting up openHAB 2.
|
||||
|
||||
This page is structured as follows:
|
||||
|
||||
{::options toc_levels="2..4"/}
|
||||
|
||||
* TOC
|
||||
{:toc}
|
||||
|
||||
## Prerequisites
|
||||
|
||||
First, be sure to check that your system has the necessary [prerequisites]({{base}}/installation/index.html#prerequisites).
|
||||
|
||||
Add the `JAVA_HOME` System Environment Variable in Windows. Navigate to:
|
||||
Add the `JAVA_HOME` System Environment Variable in Windows.
|
||||
Navigate to:
|
||||
|
||||
* Control Panel ➡️ System and Security ➡️ System ➡️ Advanced System Settings ➡️ Environment Variables ➡️ System Variables
|
||||
|
||||
Create a New System Variable based on your Java installation directory:
|
||||
|
||||
|
||||
|
||||
|
||||
The directory that openHAB is installed to must **contain no spaces**.
|
||||
On this page, we will be using `C:\openHAB2` as an example.
|
||||
|
|
@ -29,18 +37,19 @@ On this page, we will be using `C:\openHAB2` as an example.
|
|||
The openHAB runtime is distributed using a platform-independent zip file.
|
||||
To install it, follow these simple steps:
|
||||
|
||||
1. Choose between the Stable Version [  ](https://bintray.com/openhab/mvn/download_file?file_path=org%2Fopenhab%2Fdistro%2Fopenhab%2F2.0.0%2Fopenhab-2.0.0.zip) or the latest Snapshot Version [  ](https://openhab.ci.cloudbees.com/job/openHAB-Distribution/lastSuccessfulBuild/artifact/distributions/openhab/target/openhab-2.1.0-SNAPSHOT.zip) of openHAB2.
|
||||
1. Choose between the Stable Version [](https://bintray.com/openhab/mvn/download_file?file_path=org%2Fopenhab%2Fdistro%2Fopenhab%2F2.0.0%2Fopenhab-2.0.0.zip) or the latest Snapshot Version [](https://openhab.ci.cloudbees.com/job/openHAB-Distribution/lastSuccessfulBuild/artifact/distributions/openhab/target/openhab-2.1.0-SNAPSHOT.zip) of openHAB2.
|
||||
|
||||
2. Unzip the file in your chosen directory (e.g. `C:\openHAB2`)
|
||||
2. Unzip the file in your chosen directory (e.g. `C:\openHAB2`)
|
||||
|
||||
|
||||
|
||||
|
||||
3. Start the server: Launch the runtime by executing the script `C:\openHAB2\start.bat` and wait a while for it to start and complete.
|
||||
3. Start the server: Launch the runtime by executing the script `C:\openHAB2\start.bat` and wait a while for it to start and complete.
|
||||
|
||||
|
||||
|
||||
|
||||
4. Point your browser to `http://localhost:8080`. You should be looking at the openHAB [package selection page]({{base}}/configuration/packages.html).
|
||||
When you've selected an appropriate package, this page will contain the [UI]({{base}}/addons/uis.html) selection screen.
|
||||
4. Point your browser to `http://localhost:8080`.
|
||||
You should be looking at the openHAB [package selection page]({{base}}/configuration/packages.html).
|
||||
When you've selected an appropriate package, this page will contain the [UI]({{base}}/addons/uis.html) selection screen.
|
||||
|
||||
### File Locations
|
||||
|
||||
|
|
@ -59,30 +68,155 @@ Assuming a successful install, you will now have various folders inside `C:\open
|
|||
## Backup
|
||||
|
||||
Make sure that you make regular backups of the **conf** and **userdata** folders, you can zip and unzip these folders too and from openHAB installations (even across most versions).
|
||||
When you have a setup that you are happy with, it would be a good idea to make a backup of the whole `C:\openHAB2` folder. Which can be used any time after a failure.
|
||||
When you have a setup that you are happy with, it would be a good idea to make a backup of the whole `C:\openHAB2` folder.
|
||||
Which can be used any time after a failure.
|
||||
|
||||
## Updating the openHAB Runtime
|
||||
|
||||
There is currently no automatic update script for Windows. To update manually, download a later version of the openHAB distribution zip file and follow these steps:
|
||||
There is currently no automatic update script for Windows.
|
||||
To update manually, download a later version of the openHAB distribution zip file and follow these steps:
|
||||
|
||||
1. Stop the openHAB process if it is currently running.
|
||||
2. Backup openHAB as described above.
|
||||
3. Delete the following files from your existing install:
|
||||
- `userdata\etc\all.policy`
|
||||
- `userdata\etc\branding.properties`
|
||||
- `userdata\etc\branding-ssh.properties`
|
||||
- `userdata\etc\config.properties`
|
||||
- `userdata\etc\custom.properties`
|
||||
- `userdata\etc\distribution.info`
|
||||
- `userdata\etc\jre.properties`
|
||||
- `userdata\etc\profile.cfg`
|
||||
- `userdata\etc\startup.properties`
|
||||
- Any file in `userdata\etc` that starts with `org.apache.karaf`
|
||||
- The `userdata\cache` folder
|
||||
- The `userdata\tmp` folder
|
||||
4. Copy and paste the new `userdata` folder over your existing install, when prompted **do not overwrite existing files**.
|
||||
- `userdata\etc\all.policy`
|
||||
- `userdata\etc\branding.properties`
|
||||
- `userdata\etc\branding-ssh.properties`
|
||||
- `userdata\etc\config.properties`
|
||||
- `userdata\etc\custom.properties`
|
||||
- `userdata\etc\distribution.info`
|
||||
- `userdata\etc\jre.properties`
|
||||
- `userdata\etc\profile.cfg`
|
||||
- `userdata\etc\startup.properties`
|
||||
- Any file in `userdata\etc` that starts with `org.apache.karaf`
|
||||
- The `userdata\cache` folder
|
||||
- The `userdata\tmp` folder
|
||||
4. Copy and paste the new `userdata` folder over your existing install, when prompted **do not overwrite existing files**
|
||||
5. Copy and paste the new `runtime` folder over your existing install, when prompted **overwrite all existing files**
|
||||
|
||||
## Starting openHAB as a service
|
||||
## Starting openHAB as a Service
|
||||
|
||||
(work in progress...)
|
||||
By installing the openHAB process as a service in Windows, you can:
|
||||
|
||||
* Launch it automatically upon system startup
|
||||
* Run it in the background
|
||||
|
||||
**Windows Service Installation Steps**
|
||||
|
||||
1. Complete the [prerequisites](#prerequisites) and regular [installation](#installation) steps, including the package selection
|
||||
|
||||
2. Issue the following two commands in your openHAB console:
|
||||
```shell
|
||||
feature:install service-wrapper
|
||||
wrapper:install --name "openHAB2" --display "openHAB2" --description "openHAB 2 Service"
|
||||
```
|
||||
|
||||
|
||||
|
||||
3. Shutdown the openHAB instance by typing `logout` in the currently running console.
|
||||
|
||||
4. Update the newly created `C:\openHAB2\userdata\etc\openHAB2-wrapper.conf` to include all necessary parameters.
|
||||
|
||||
* Copy all the config text from the below section and paste it in your `openHAB2-wrapper.conf`, replacing all existing content.
|
||||
* Adapt the first entry (`OPENHAB_HOME`) to match your openHAB installation directory.
|
||||
|
||||
```conf
|
||||
#*******************************************************
|
||||
# openHAB2-wrapper.conf for Windows Service Installation
|
||||
#*******************************************************
|
||||
|
||||
# openHAB installation dir (Adapt this first setting to your system)
|
||||
set.default.OPENHAB_HOME=C:\openHAB2
|
||||
|
||||
# Wrapper Properties
|
||||
set.default.OPENHAB_CONF=%OPENHAB_HOME%\conf
|
||||
set.default.OPENHAB_RUNTIME=%OPENHAB_HOME%\runtime
|
||||
set.default.OPENHAB_USERDATA=%OPENHAB_HOME%\userdata
|
||||
set.default.OPENHAB_LOGDIR=%OPENHAB_USERDATA%\logs
|
||||
set.default.KARAF_HOME=%OPENHAB_RUNTIME%
|
||||
set.default.KARAF_BASE=%OPENHAB_USERDATA%
|
||||
set.default.KARAF_DATA=%OPENHAB_USERDATA%
|
||||
set.default.KARAF_ETC=%OPENHAB_USERDATA%\etc
|
||||
set.default.PATH=%PATH%;%KARAF_BASE%\lib;%KARAF_HOME%\lib
|
||||
|
||||
# Java Application
|
||||
wrapper.working.dir=%KARAF_BASE%
|
||||
wrapper.java.command=%JAVA_HOME%/bin/java
|
||||
wrapper.java.mainclass=org.apache.karaf.wrapper.internal.service.Main
|
||||
wrapper.java.classpath.1=%KARAF_HOME%/lib/boot/*.jar
|
||||
wrapper.java.classpath.2=%KARAF_DATA%/lib/wrapper/*.jar
|
||||
wrapper.java.library.path.1=%KARAF_DATA%/lib/wrapper/
|
||||
|
||||
# Java Parameters
|
||||
wrapper.java.additional.1=-Dkaraf.home="%KARAF_HOME%"
|
||||
wrapper.java.additional.2=-Dkaraf.base="%KARAF_BASE%"
|
||||
wrapper.java.additional.3=-Dkaraf.data="%KARAF_DATA%"
|
||||
wrapper.java.additional.4=-Dkaraf.etc="%KARAF_ETC%"
|
||||
wrapper.java.additional.5=-Dcom.sun.management.jmxremote
|
||||
wrapper.java.additional.6=-Dkaraf.startLocalConsole=false
|
||||
wrapper.java.additional.7=-Dkaraf.startRemoteShell=true
|
||||
wrapper.java.additional.8=-Djava.endorsed.dirs="%JAVA_HOME%/jre/lib/endorsed;%JAVA_HOME%/lib/endorsed;%KARAF_HOME%/lib/endorsed"
|
||||
wrapper.java.additional.9=-Djava.ext.dirs="%JAVA_HOME%/jre/lib/ext;%JAVA_HOME%/lib/ext;%KARAF_HOME%/lib/ext"
|
||||
wrapper.java.additional.10=-Dopenhab.home="%OPENHAB_HOME%"
|
||||
wrapper.java.additional.11=-Dopenhab.conf="%OPENHAB_HOME%\conf"
|
||||
wrapper.java.additional.12=-Dopenhab.runtime="%OPENHAB_HOME%\runtime"
|
||||
wrapper.java.additional.13=-Dopenhab.userdata="%OPENHAB_HOME%\userdata"
|
||||
wrapper.java.additional.14=-Dopenhab.logdir="%OPENHAB_USERDATA%\logs"
|
||||
wrapper.java.additional.15=-Dfelix.cm.dir="%OPENHAB_HOME%\userdata\config"
|
||||
wrapper.java.additional.16=-Dorg.osgi.service.http.port=8080
|
||||
wrapper.java.additional.17=-Dorg.osgi.service.http.port.secure=8443
|
||||
wrapper.java.maxmemory=512
|
||||
|
||||
# Wrapper Logging Properties
|
||||
wrapper.console.format=PM
|
||||
wrapper.console.loglevel=INFO
|
||||
wrapper.logfile=%OPENHAB_USERDATA%\logs\wrapper.log
|
||||
wrapper.logfile.format=LPTM
|
||||
wrapper.logfile.loglevel=INFO
|
||||
wrapper.logfile.maxsize=10m
|
||||
wrapper.logfile.maxfiles=5
|
||||
wrapper.syslog.loglevel=NONE
|
||||
|
||||
# Wrapper Windows Properties
|
||||
wrapper.console.title=openHAB2
|
||||
wrapper.ntservice.name=openHAB2
|
||||
wrapper.ntservice.displayname=openHAB2
|
||||
wrapper.ntservice.description=openHAB 2 Service
|
||||
wrapper.ntservice.dependency.1=
|
||||
wrapper.ntservice.starttype=AUTO_START
|
||||
wrapper.ntservice.interactive=false
|
||||
```
|
||||
|
||||
5. Open an elevated command prompt and type the following commands:
|
||||
|
||||
```text
|
||||
C:\openHAB2\userdata\bin\openHAB2-service.bat install
|
||||
net start "openHAB2"
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
6. Your openHAB Windows service is now installed and running.
|
||||
Validate proper operations by:
|
||||
|
||||
* Browsing to [http://localhost:8080](http://localhost:8080)
|
||||
* Verifying that the Windows Service is running and set to Automatic Startup type.
|
||||
Use `services.msc` and find the `openHAB2` service.
|
||||
|
||||
* Logging in with an SSH client to the console (see info below)
|
||||
|
||||
### Connecting to the openHAB console
|
||||
|
||||
* Install an SSH client application, e.g., [Putty](https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html), [KiTTY](http://kitty.9bis.net/) or [Xshell 5](https://www.netsarang.com/products/xsh_overview.html)
|
||||
* Setup a session with the following parameters:
|
||||
* Host: 127.0.0.1
|
||||
* Port: 8101
|
||||
* Username: `openhab`
|
||||
* Password: `habopen`
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue