How to Install Oxygen Feedback Enterprise Service on Linux

useradd feedback

export OXYGEN_FEEDBACK_INSTALL_DIR=/home/feedback/oxygen-feedback
sudo mkdir $OXYGEN_FEEDBACK_INSTALL_DIR
sudo chown feedback: $OXYGEN_FEEDBACK_INSTALL_DIR

cd $OXYGEN_FEEDBACK_INSTALL_DIR
# Copy the downloaded archive here
unzip oxygen-feedback-enterprise.zip

1. Edit feedback-home.properties:

   sudo vi $OXYGEN_FEEDBACK_INSTALL_DIR/oxygen-feedback-1.3/feedback-home.properties

2. Set the feedback.home property:

   # Oxygen Feedback home path property (by default, the current installation directory)
   feedback.home=<oxygen-feedback-user-home-dir>/oxygen-feedback-home

3. Move the config and data directories to the Feedback home directory. For example:

   export OXYGEN_FEEDBACK_HOME_DIR=/home/feedback/oxygen-feedback-home
   cp -R $OXYGEN_FEEDBACK_INSTALL_DIR/oxygen-feedback-1.3/config $OXYGEN_FEEDBACK_HOME_DIR
   cp -R $OXYGEN_FEEDBACK_INSTALL_DIR/oxygen-feedback-1.3/data $OXYGEN_FEEDBACK_HOME_DIR

http.port=8081

1. Create a database user that will be used by Oxygen Feedback Enterprise to connect to the database. For example, feedback_db_user:

   CREATE USER 'feedback_db_user'@'localhost' IDENTIFIED BY 'password';

   This creates a user that can connect from the localhost. For more details, see: https://dev.mysql.com/doc/refman/8.0/en/create-user.html.

2. Create the database where Oxygen Feedback Enterprise will store its data. For example, feedback_db:

   CREATE DATABASE feedback_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

   The database must have a character set of UTF8. For more details, see: https://dev.mysql.com/doc/refman/8.0/en/create-database.html.

3. The user needs to have permission to connect to the database, create and populate the tables, etc. You can provide these permissions with the following command:

   GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, REFERENCES, INDEX, ALTER, CREATE TEMPORARY TABLES, 
   CREATE VIEW, EVENT, TRIGGER, SHOW VIEW, CREATE ROUTINE, ALTER ROUTINE, EXECUTE ON feedback_db.* 
   TO 'feedback_db_user'@'localhost';
   flush privileges;

   For more details, see: https://dev.mysql.com/doc/refman/8.0/en/grant.html.

4. Copy the MySQL JDBC driver:
   1. Go to https://dev.mysql.com/downloads/connector/j/8.0.html.
   2. For Select Operating System, chooses Platform Independent.
   3. Download the connector.
   4. Extract the contents from the downloaded MySQL connector JAR file to the installation directory. For example:

      $OXYGEN_FEEDBACK_INSTALL_DIR/oxygen-feedback-1.3/lib 

      Note: Only the MySQL connector JAR file should be copied to the directory mentioned above, and not the entire archive content.
5. Configure Oxygen Feedback Enterprise to connect to the database:
   1. Go to /config and create a file named feedback-database.properties.
   2. Edit the file and update it with your configuration. An example is provided in the feedback-database-mysql.properties file. It should look like this:

      # The database management system type. For example MySQL or PostgreSQL.
      feedback.database.type = mysql
      # The database URL in format: jdbc:mysql://<hostname>:<port>/<database>
      # For example: jdbc:mysql://localhost:3306/feedback_db
      feedback.datasource.url=jdbc:mysql://localhost:3306/feedback_db
      # The username to access the database
      feedback.datasource.username=feedback_db_user
      # The password to access the database
      feedback.datasource.password=password

1. Create a database user that will be used by Oxygen Feedback Enterprise to connect to the database. For example, feedback_db_user:

   CREATE USER feedback_db_user WITH PASSWORD 'password';

   For more details, see: https://www.postgresql.org/docs/12/sql-createuser.html.

2. Create the database where Oxygen Feedback Enterprise will store its data. For example, feedback_db:

   CREATE DATABASE feedback_db ENCODING='UTF8' LC_COLLATE='C' LC_CTYPE='C' TEMPLATE='template0';

   The database must have the encoding set of UTF8. For more details, see: https://www.postgresql.org/docs/12/sql-createdatabase.html.

3. The user needs to have permission to connect to the database, create and populate the tables, etc. You can provide these permissions with the following command:

   GRANT ALL PRIVILEGES ON DATABASE feedback_db TO feedback_db_user;

   For more details, see: https://www.postgresql.org/docs/12/sql-grant.html.

4. Configure Oxygen Feedback Enterprise to connect to the database:
   1. Go to /config and create a file named feedback-database.properties.
   2. Edit the file and update it with your configuration. An example is provided in the feedback-database-psql.properties file. It should look like this:

      # The database management system type. For example MySQL or PostgreSQL.
      feedback.database.type = postgresql
      # The database URL in format: jdbc:postgresql://<hostname>:<port>/<database>
      # For example: jdbc:postgresql://localhost:5432/feedback_db
      feedback.datasource.url=jdbc:postgresql://localhost:5432/feedback_db
      # The username to access the database
      feedback.datasource.username=feedback_db_user
      # The password to access the database
      feedback.datasource.password=password

1. Go to the OXYGEN_FEEDBACK_HOME_DIR (or to the Feedback server installation directory) and create a new file called licensekey.txt.

   cd $OXYGEN_FEEDBACK_HOME_DIR
   touch licensekey.txt

2. Copy and paste your license key inside the licensekey.txt file using a text editor or use:

   cat >> licensekey.txt
   # Paste license
   # Press CTRL-D

Application Host URL

The server URL where the application will be deployed. It must contain the protocol and port and it will be used in the email notifications:

feedback.server.host.url=http://example.com

Image Upload Configuration

Image upload allowed extensions:

feedback.upload.extensions=jpg,jpeg,png,gif

Sets the maximum allowed size of an image in KB.

feedback.max.file.upload.size=2048

Set it to true for images to be validated (extension and size) before being uploaded or false to not validate them.

feedback.image.validation=true

Comment Configuration

Sets the limit of how many characters a comment can have.

feedback.max.comment.character.size=10000

Sets the number of days that a deleted comment can be restored. After that, the comment is permanently deleted.

feedback.comment.expiration.period=30

Accounts Management Configuration

Sets the number of hours that a newly created account can be activated before it expires.

feedback.account.expiration.period=24

Sets the number of days that a deleted account can be recovered.

feedback.account.termination.period=14

Role Change Settings

Sets the number of hours that a site ownership transfer is valid. If the transfer is not accepted within that time, it will automatically be cancelled:

feedback.valid.transfer.site.ownership.period=24

Sets the number of days that a role change is pending. If not accepted within that time, it will automatically be cancelled.

feedback.valid.role.change.period=1

Cross-Domain Cookies Settings

Controls whether or not the Feedback server sets the SameSite=None attribute on the cookies sent to the client.

If the application is configured to run on HTTP, then this property should be set to false for the login to work properly.

feedback.cookie.samesite.none=true

Basic Authentication

Controls whether or not Basic Authentication is enabled.

feedback.basic.authentication.enabled=true

Configure the SMTP Outgoing Server

The SMTP name:

spring.mail.host=smtp.example.com

The SMTP port:

spring.mail.port=25

Configure the From Email Address

The name that will be displayed in the From field for email messages sent by this server:

feedback.email.sender=company@sender.example.com

Configure SMTP Authentication

The user name used in the authenticated SMTP:

spring.mail.username=<user>

The password used in the authenticated SMTP:

spring.mail.password=<password>

Configure STARTTLS Protocol Command

If true, it enables the use of the STARTTLS command (if supported by the server) to switch the connection to a TLS-protected connection before issuing any login commands. If the server does not support STARTTLS, the connection continues without the use of TLS:

spring.mail.properties.mail.smtp.starttls.enable=true

If true, it requires the use of the STARTTLS command. If the server does not support the STARTTLS command, or the command fails, the connect method will fail. The default is false.

spring.mail.properties.mail.smtp.starttls.required=false

Configure SSL Authentication

If set to true, it uses SSL to connect and uses the SSL port by default. The default is false for the SMTP protocol and true for the SMTPS protocol:

spring.mail.properties.mail.smtp.ssl.enable=true

Specifies the port to connect to when using the specified socket factory. If not set, the default port will be used.

spring.mail.properties.mail.smtp.ssl.socketFactory.port=465

Advanced Properties

The default message encoding:

spring.mail.default-encoding=UTF-8

Oxygen Feedback Enterprise uses JavaMail for sending emails and it allows additional properties to be set using the following pattern:

spring.mail.properties.{JAVA.MAIL.PROPERTY}=

See all available properties in the JavaMail documentation at: https://javaee.github.io/javamail/docs/api/com/sun/mail/smtp/package-summary.html#properties.

spring.mail.properties.*=

1. Enable LDAP authentication support by editing the $OXYGEN_FEEDBACK_HOME_DIR/config/feedback-ldap.properties file and set the feedback.ldap.enabled property to true.
2. Configure the URL for your LDAP server by setting the feedback.ldap.serverUrl property. For example:

   feedback.ldap.serverUrl=ldap://ldap.example.com:33389/dc=myco,dc=org

3. Specify the pattern for the search filter used to identify a user entity on the LDAP server by setting the feedback.ldap.userSearchFilter property. For example:

   (|(mail={0})(uid={0}))

   The substituted parameter is the user's login name. This example pattern enables user authentication with both the username and email address.

4. Specify the name of the email attribute for the LDAP user entity by setting the feedback.ldap.emailAttribute property.
   Important: For the authentication to work, it is mandatory that your LDAP users entities have an associated email address.
5. Specify whether or not new account registration is allowed by setting the feedback.ldap.userRegistrationEnabled property. For example, to disable new account registration (hides the Sign Up form in the login page):

   feedback.ldap.userRegistrationEnabled=false

   Note: The feedback.ldap.userRegistrationEnabled property does not disable the possibility of authenticating using a local (DB) account. It only hides the Sign Up form, thus inhibiting the possibility of creating new local user accounts.

###########################################################################
# Stores the configuration properties for the LDAP authentication support #
###########################################################################

# Flag used to enable the LDAP authentication support.
feedback.ldap.enabled=true

# Flag used to enable users to register with a Feedback local (non-ldap) account.
feedback.ldap.userRegistrationEnabled=true

# Specifies the LDAP server URL of the form ldap://localhost:389/base_dn
# LDAPS URLs may be used
# For example: "ldap://ldap.example.com:33389/dc=myco,dc=org".
feedback.ldap.serverUrl=ldap://ldap.example.com:33389/dc=myco,dc=org

# The LDAP filter used to search for users. 
# For example "(uid={0})". The substituted parameter is the user's login name.
feedback.ldap.userSearchFilter=(|(mail={0})(uid={0}))

# Context name to search for users in, relative to the Base DN specified in the server URL
# May be empty -> the search will be performed against the Base DN
# For example: "cn=users"
# => Considering "ldap://ldap.example.com:33389/dc=myco,dc=org" as server URL, then the users will be searched under "cn=users,dc=myco,dc=org"
feedback.ldap.userSearchBase=cn=users

# The name of the email attribute of the user entity.
# Defaults to 'mail'
feedback.ldap.emailAttribute=mail

# The name of the attribute containing the user's full (display) name.
# Defaults to 'cn'
feedback.ldap.nameAttribute=cn

# Credentials of the user that has privileges to search the directory. Simple binding is used.
# If not provided, anonymous bind is used.
feedback.ldap.admin.dn=cn=admin,cn=users,dc=myco,dc=org
# Must be non-empty if 'feedback.ldap.admin.dn' is provided
feedback.ldap.admin.password=myPassword

• feedback.ldap.admin.dn - Specifies the distinguished name of the user with LDAP searching privileges.
• feedback.ldap.admin.password - Specifies the password of the user with LDAP searching privileges.

• feedback.ldap.userSearchBase - Specifies the context name to be used when searching for users (relative to the Base DN specified in the server URL). If this property is left empty, the search will be performed against the Base DN.
• feedback.ldap.nameAttribute - Specifies the name of the attribute that contains the full display name of the user. If omitted, the value defaults to cn.

1. Go to the location where the Feedback server is deployed (e.g. http://localhost:8080).
2. In the resulting setup page, define your first platform admin.
3. Enter the required information and click the Create button.
   Note: The setup page is only visible the first time the application is started. After the first platform admin is defined, that page will no longer be available.