The documentation lacks information on whether the "regular" (non-SYSTEM) user should be created prior to the installation.

It just references how the database secret should look like here - {DB_USER}:{DB_PASSWORD}, however it does not say whether a user with these credentials should be created. It actually DOES need to exist, so this has to be clearly stated in the documentation (see more details in the comments).

There are also some limitations related to the password of this user:

• apparently the password of the "regular" user should be unique (do not match with SYSTEM user password, for example, otherwise it may cause ORA-28007: the password cannot be reused, see private Jira THREESCALE-5450.
• there might be a potential issue if the parameters PASSWORD_REUSE_TIME and PASSWORD_REUSE_MAX are set on the DB, see this comment in private Jira.

The reason for this is that the DB setup script executes ALTER USER {DB_USER} IDENTIFIED BY {DB_PASSWORD}. So, probably the documentation can just point this out, and ask the user to ensure this command can be executed successfully prior to the installation.

There seem to be some issues with using special characters in the password: THREESCALE-7187. However it still needs to be confirmed whether it is a bug, or it's just the matter of escaping special characters properly in the secret (in which case the documentation also needs to call it out).