Post-installation configuration

The following notes are applicable for RHEL 8 and RHEL 9:

P4 Code Review 2020.2 and later: these versions of P4 Code Review uses the Remi repository for RHEL 8 and RHEL 9. This provides PHP 8.x installed in the standard file system structure. This means that the old httpd24-httpd version of Apache is no longer needed, and the standard system version of Apache is being used again.

The SCL Apache site configuration file was installed at this location for P4 Code Review 2019.1 to 2020.1:

/opt/rh/httpd24/root/etc/httpd/conf.d/perforce-swarm-site.conf

If this exists when P4 Code Review is upgraded to 2020.2 and later, this file is copied to /etc/httpd/conf.d/perforce-swarm-site.conf if there is no file at the destination. It is also re-written to change references from /var/log/httpd24 to /var/log/httpd

If a site configuration file for P4 Code Review already exists in /etc/httpd, the copy and re-write is not performed.

After upgrade, httpd24-httpd is disabled.
To avoid seeing the Apache HTTP server Linux test page when you start the Apache server, comment out the content of the welcome.conf file located in the /etc/httpd/conf.d/ directory.
To avoid loading the Apache HTTP server example configuration instead of the P4 Code Review configuration when the Apache server starts, rename the autoindex.conf file located in the /etc/httpd/conf.d/ directory to z-autoindex.conf or similar. This is required because Apache runs the first conf file it finds in the /etc/httpd/conf.d/ directory (alphabetical order) and that must be the perforce-swarm-site.conf file.

Once the helix-swarm package has been installed, additional configuration is required. Perform the following steps:

Use the P4 Code Review post-installation script to configure P4 Code Review on the server hosting P4 Code Review.

The P4 Code Review post-installation configuration script can be used in a few different ways. The steps below outline the most straightforward configuration using an interactive install, but you can review the options by running:

sudo /opt/perforce/swarm/sbin/configure-swarm.sh -h
- If your P4 Server is configured for P4 AS, the P4 Server must be temporarily configured to allow fall-back to passwords while you establish a connection to the P4 Server. Run the following command on the P4 Server to enable fall-back to passwords:
  
  p4 configure set auth.sso.allow.passwd=1
- To use P4 ServerExtensions, make sure that Extensions are installed and configured on your P4 Server before running the configuration script. For information about P4 ServerExtensions , see p4 extension in P4 CLI Reference and Extensions overview in P4 Server Administration Documentation.
Run the interactive post-installation configuration script:

sudo /opt/perforce/swarm/sbin/configure-swarm.sh

The configuration script displays the following summary:
```
------------------------------------------------------------
configure-swarm.sh: Thu Aug 26 11:29:49 PDT 2021: commencing configuration of Swarm
Summary of arguments passed:
Interactive?       [yes]
Force?             [no]
P4PORT             [(not specified, will prompt)]
Swarm user         [(not specified, will prompt, will suggest swarm)]
Swarm password     [(not specified, will prompt)]
Email host         [(not specified, will prompt)]
Create depot       [(not specified, will prompt)]
Bypass Lock        [(not specified)] 
Use Extensions?    [(not specified, will prompt)] 
Swarm host         [(not specified, will prompt, will suggest myhost)]
Swarm port         [(default (80))]
Swarm base URL     [(default (empty))]
Create Swarm user? [yes]
Super user         [(not specified, will prompt)]
Super password     [(not specified, will prompt)]
```
Provide information to the configuration script.

After the summary, the configuration script prompts for the following information:
1. Specify a value for P4PORT in the form: my-helix-core-server:1666
```
No P4PORT specified

P4 Code Review requires a connection to a Helix Core Server.
Please supply the P4PORT to connect to.

Helix Core Server address (P4PORT):
```
  Specify the hostname and port for your P4 Server. If defined, the value for P4PORT is used as the default. The configuration script verifies that it can connect:
```
-response: [myp4host:1666]

Checking P4PORT [myp4host:1666]...
-P4 command line to use: [/opt/perforce/bin/p4 -p myp4host:1666]
Attempting connection to [myp4host:1666]...
-connection successful:
  Server address: myp4host:1666
  Server version: P4D/LINUX26X86_64/2021.1/2179737 (2021/04/24)
  Server license: 10000 users (support ends 2022/05/16)
  Server license-ip: 192.168.0.1
```
  If your P4 Server is deployed using the commit-edge architecture, ensure that the P4 Code Review port value points to the commit server.
  For more information, see the Commit-edge chapter in the P4 Server Administration Documentation.
2. Specify the userid and password of a normal user with admin-level privileges in the P4 Server.
```
Checking Swarm user credentials...
No Swarm user specified

Swarm requires a Helix user account with 'admin' rights.
Please provide a username and password for this account.
If this account does not have 'admin' rights, it will 
be set for this user.

Helix username for the Swarm user [swarm]:
```
  Enter the userid. The default is swarm.
```
-response: [swarm]
						
Helix password or login ticket for the P4 Code Review user (typing hidden):
```
  To allow users to clean up reviews created by other users when the review is committed, the P4 Server user account must have super permissions.
  See Review cleanup.
  
  Enter the login ticket, or password, for the userid.
  
  You must use a long-lived login ticket for the P4 Code Review user.
  
  You can obtain a login ticket by running (in another shell):
  
  p4 -p myp4host:1666 -u userid login -p
  
  If the login ticket you provide expires in less than a year, you will receive a warning. If you receive this warning, ask your P4 Server administrator to make sure the swarm user is in a P4 Server group that has the Timeout field set to a year or more. See p4 group in the P4 CLI Reference.
```
Checking Swarm user credentials...
-checking if user [swarm] exists in [myp4host:1666]...
-user exists
Obtaining Helix login ticket for [swarm] in [myp4host:1666]...
-login ticket obtained
Checking user [swarm]'s ticket against [myp4host:1666]...
-login ticket is good
Checking user [swarm] has at least access level [admin]...
-user has maximum access level [admin]
-user meets minimum access level [admin]
```
3. Specify the hostname for the P4 Code Review UI.
```
swarm needs a distinct hostname that users can enter into their browsers to
access Swarm. Ideally, this is a fully-qualified domain name, for example
'swarm.company.com', but it can be just a hostname, for example 'swarm'.

Whatever hostname you provide should be Swarm-specific and not shared with
any other web service on this host.

Note that the hostname you specify typically requires configuration in your
network's DNS service. If you are merely testing Swarm, you can add a
hostname->IP mapping entry to your computer's hosts configuration.

Hostname for this Swarm server [myhost]:
```
  The default is the current hostname
  The configuration script does not verify that the hostname actually works (DNS configuration may not exist yet).
4. Specify a mail relay host or leave empty to use your local mail handler.
```
P4 Code Review can use a mail relay host to send email notifications. Leave empty if
you want to use the local mail handler (for example Sendmail, Postfix etc),
or enter a hostname (for example mx.yourdomain.com) to use a relay host.
 
Mail relay host: 
```
  The configuration script does not verify that the mail relay host you provide actually accepts SMTP connections.
5. To enable file attachments on comments, P4 Code Review must have a depot location to save the attachment files in. P4 Code Review can create this depot and set the depot protections for you automatically or you can manually set it up later.
  
  You must be a user with super user permissions to create the .swarm depot and set protections.
```
- checking depot 

P4 Code Review has the ability to store attachments against review comments. To
do this, it needs to have a depot where they are stored. By default,
this is //.swarm. We can create the depot for you automatically, and
set the protections on it to the following: 

list user * * -//.swarm/...
admin user swarm * //.swarm/...
super user super * //.swarm/...
 
If you want to enable attachments, and for the depot and protections
to be set up for you, then say yes here. If you say no, then you can
still do this manually later.
Do you want to create a .swarm depot and set protections? (y/n) [n]
```
  When prompted to automatically create the depot, select one of the following:
  - Type y to automatically create the .swarm depot and set protections.
  - Type n skip depot creation. You can create the depot and set the protections manually later if you want to, see Comment attachments.
  If you choose to automatically create the depot, the script will create the depot, set the protections, and report when completed.
```
Depot //.swarm successfully created. Protections have been set so
that only the 'swarm' and 'super' have permissions to
access it directly. 
```
6. Configure the following to enable communication between P4 Code Review and P4 Server.
  - Configure the P4 Server to promote all shelved changes. For more information, see Configure the P4 Server to promote all shelved changes.
  - Configure the p4 key access on P4 Server. For more information on p4 key and their access levels, see Hiding P4 Code Review storage from regular users.
  - Allow P4 Code Review to work with 'exclusive open' files. For more information about exclusive locks, see Handling Exclusive Locks.
  Run the following to set these three configurations:
```
p4 configure dm.shelve.promote=1
p4 configure set dm.keys.hide=2
p4 configure set filetype.bypasslock=1
```
7. P4 Code Review needs to know about some P4 Server events to operate correctly. Use P4 Server Extensions (recommended) or P4 Server Triggers to notify P4 Code Review about these events. P4 Server Extensions are easier to install and maintain than triggers.
  
  You must be a user with super user permissions to install and configure P4 Server Extensions.
```
Do you want to use Swarm's Helix Core server extension?
Configuring Server extensions requires super user access to the Helix Server.
If you install the Swarm server extension, do not install the Swarm triggers.
Server extensions are supported for:
* Linux: Helix server 19.2 and later.
* Windows: Helix server 21.2 and later. 

Use server extensions? 
```
  When prompted to Use server Extensions, choose one of the following:
  - Recommended: Type y to use P4 Server Extensions. The configuration script will try and install and configure the P4 Server extension.
  - Type n to use P4 Server Triggers. Triggers must be installed manually, P4 Code Review will prompt you to do this when the P4 Code Review configuration script completes.
  If you choose to install the P4 Server Extensions, the script will:
  - check your P4 Server supports P4 Server Extensions
  - check if P4 Server Extensions are installed and configured on your P4 Server. If they are, P4 Code Review does not need to do anything
  - install and configure the P4 Server extension on your P4 Server
  If any of these checks fail, P4 Code Review will not install the P4 Server extension and will report the issues on the configuration summary screen.

If you have installed P4 Code Review on a host that does not provide other web services, you may wish to disable Apache's default site configuration. Doing so means that regardless of the hostname a user might use to reach the web server hosting P4 Code Review, P4 Code Review would be presented.

Be aware that disabling Apache's default site configuration could disable existing web services or content.

Disabling Apache's default site configuration on Ubuntu hosts is easy. Run:

$ sudo a2dissite 000-default

For non-standard Apache installations, you would need to manually adjust the Apache configuration. Such changes require familiarity with Apache configuration; for more details, see Apache HTTP server project.

To add Swarm as an HTML tab in the P4 Visual Client (P4V), see HTML Tabs section in the P4VJS Developer Guide.

Configure SELinux for P4 Code Review, see SELinux configuration.
The basic P4 Code Review configuration is now complete.

If your P4 Server is configured for P4 AS, you can force all of your users to authenticate via your Identity Provider (IdP) by disabling fall-back to passwords. To disable fall-back to passwords on the P4 Server, run the following command:

p4 configure set auth.sso.allow.passwd=0
Do one of the following:
- If the P4 Server extension was installed by the configuration script: Review the post-install configuration options to customize your P4 Code Review installation, see Post-install configuration options.
- If the P4 Server extension was not installed, you must install triggers: Configure P4 Server for P4 Code Review, see Installing triggers.