summaryrefslogtreecommitdiffstats
path: root/src/site-docs/adoc/fragments/install-guide/configure.adoc
blob: 97388f8f75608cd9819ed3a22e925412a6a09afd (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
//
// ============LICENSE_START=======================================================
//  Copyright (C) 2016-2018 Ericsson. All rights reserved.
// ================================================================================
// This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE
// Full license text at https://creativecommons.org/licenses/by/4.0/legalcode
// 
// SPDX-License-Identifier: CC-BY-4.0
// ============LICENSE_END=========================================================
//
// @author Sven van der Meer (sven.van.der.meer@ericsson.com)
//

== System Configuration
Once APEX is installed, a few configurations need to be done:

- Create an APEX user and an APEX group (optional, if not installed using RPM and DPKG)
- Create environment settings for `APEX_HOME` and `APEX_USER`, required by the start scripts
- Change settings of the logging framework (optional)
- Create directories for logging, required (execution might fail if directories do not exist or cannot be created)

=== APEX User and Group
On smaller installations and test systems, APEX can run as any user or group.

However, if APEX is installed in production, we strongly recommend you set up a dedicated user for running APEX.
This will isolate the execution of APEX to that user.
We recommend you use the userid `apexuser` but you may use any user you choose.

The following example, for UNIX, creates a group called `apexuser`, an APEX user called `apexuser`, adds the group to the user, and changes ownership of the APEX installation to the user.
Substitute `<apex-dir>` with the directory where APEX is installed.

[source%nowrap,sh,numbered]
----
# sudo groupadd apexuser
# sudo useradd -g apexuser apexuser
# sudo chwon -R apexuser:apexuser <apex-dir>
----

For other operating systems please consult your manual or system administrator.


=== Environment Settings: APEX_HOME and APEX_USER
The provided start scripts for APEX require two environment variables being set:

- `APEX_USER` with the user under whos name and permission APEX should be started (Unix only)
- `APEX_HOME` with the directory where APEX is installed (Unix, Windows, Cygwin)

The first row in the following table shows how to set these environment variables temporary (assuming the user is `apexuser`).
The second row shows how to verify the settings.
The last row explains how to set those variables permanently.

[width="100%",options="header",cols="5a,5a"]
|====================
| Unix, Cygwin (bash/tcsh) | Windows
|
[source%nowrap,bash,numbered]
----
# export APEX_USER=apexuser
# cd /opt/app/policy/apex-pdp/apex-pdp
# export APEX_HOME=`pwd`
----

[source%nowrap,tcsh,numbered]
----
# setenv APEX_USER apexuser
# cd /opt/app/policy/apex-pdp/apex-pdp
# setenv APEX_HOME `pwd`
----
|
[source%nowrap,bat,numbered,subs="attributes+"]
----
>set APEX_HOME=C:\apex\apex-full-{release-version}
----

|
[source%nowrap,sh,numbered]
----
# env \| grep APEX
APEX_USER=apexuser
APEX_HOME=/opt/app/policy/apex-pdp/apex-pdp
----
|
[source%nowrap,bat,numbered,subs="attributes+"]
----
>set APEX_HOME
APEX_HOME=\apex\apex-full-{release-version}
----

|====================


==== Making Environment Settings Permanent (Unix, Cygwin)
For a per-user setting, edit the a user's `bash` or `tcsh` settings in `~/.bashrc` or `~/.tcshrc`.
For system-wide settings, edit `/etc/profiles` (requires permissions).


==== Making Environment Settings Permanent (Windows)
On Windows 7 do

- Click on the *Start* Menu
- Right click on *Computer*
- Select *Properties*

On Windows 8/10 do

- Click on the *Start* Menu
- Select *System*

Then do the following

- Select *Advanced System Settings*
- On the *Advanced* tab, click the *Environment Variables* button 
- Edit an existing variable, or create a new System variable: 'Variable name'="APEX_HOME", 'Variable value'="C:\apex\apex-full-{release-version}"

For the settings to take effect, an application needs to be restarted (e.g. any open `cmd` window).



=== Edit the APEX Logging Settings
Configure the APEX logging settings to your requirements, for instance:

- change the directory where logs are written to, or
- change the log levels

Edit the file `$APEX_HOME/etc/logback.xml` for any required changes.
To change the log directory change the line

`<property name="VAR_LOG" value="/var/log/onap/policy/apex-pdp/" />`

to

`<property name="VAR_LOG" value="/PATH/TO/LOG/DIRECTORY/" />`

On Windows, it is recommended to change the log directory to:

`<property name="VAR_LOG" value="C:/apex/apex-full-{release-version}/logs" />`

Note: Be careful about when to use `\` vs. `/` as the path separator!


=== Create Directories for Logging
Make sure that the log directory exists.
This is important when APEX was installed manually or when the log directory was changed in the settings (see above).

[width="100%",options="header",cols="5a,5a"]
|====================
| Unix, Cygwin | Windows
|
[source%nowrap,sh,numbered]
----
mkdir -p /var/log/onap/policy/apex-pdp
chown -R apexuser:apexuser /var/log/onap/policy/apex-pdp
----
|
[source%nowrap,bat,numbered,subs="attributes+"]
----
>mkdir C:\apex\apex-full-{release-version}\logs
----
|====================