Deployment Guide

This guide describes what you need to consider before integrating WANdisco's Access Control and/or replication technology into your SCM platform. This document cannot address every possible set of conditions so take care to anticipate problems. Contact our support team with any questions or concerns.

1. Deployment checklist

Don't skip this section! Overlooked requirements are a common cause of setup problems that are difficult to diagnose. These problems may take a lot more time to fix than you will checking the list.

You may have read the Deployment Checklist before or during an earlier evaluation of Access Control Plus. However, we strongly recommend that you reread the checklist before deployment to confirm that your system still meets all requirements.

System setup
Operating systems	We've tested the following operating systems: Red Hat Linux Enterprise Server (32 or 64 bit): 4, 5.2, 5.3, 5.4, 5.5, 5.6, 5.7, 5.8, 6, 6.1, 6.2, 6.3 CentOS: 5.2, 5.3, 5.4, 5.5, 5.6, 5.7, 6, 6.1, 6.2, 6.3 Suse Linux Enterprise Server: 11 Contact WANdisco Support for more information about running on this platform.
Reserved ports	Access Control Plus requires that several TCP ports are reserved for its exclusive use: application.port=6444: DConE port handles agreement traffic which coordinates replication between sites content.server.port=6445: Used for the replicator's payload data: account / access control changes etc. jetty.http.port=8082: Used for the MultiSite Plus management interface Plan your ports While default ports are assigned automatically if you don't select them, we do not recommend that you work with the defaults. Start your production deployment by selecting ports and verifying that they are available at all sites. Repeat with WANdisco MultiSite products: If you are running with Git MultiSite or SVN MultiSite Plus you should repeat this step for that application, making sure there are no port reservation conflicts.
Firewall or AV software	If your network has a firewall, ensure that traffic is not blocked on the reserved ports noted above. Configure any AV software on your system so that it doesn't block or filter traffic on the reserved ports.
Full connectivity	Access Control Plus requires full network connectivity between all nodes. Ensure that each node's server is able to communicate with all other servers that will host nodes in your Access Control Plus installation.
VPN	Set up `IPsec tunnel`, and ensure WAN connectivity.
VPN persistent connections	Ensure that your VPN doesn't reset persistent connections for Subversion MultiSite.
Bandwidth	Put your WAN through realistic load testing before going into production. You can then identify and fix potential problems before they the impact productivity.
DNS setup	Use IP addresses instead of DNS hostnames, this ensures that DNS problems won't hinder performance. If you are required to use hostnames, test your DNS servers performance and availability prior to going into production.
Deployment modes	The deployment mode is completely controlled by the license.key file. If you need to run in a different deployment mode, or change any othe aspect of your license, see License updates. Integration with SVN MultiSite Plus: See Deployment Guide for SVN MultiSite Plus. Integration with Git MultiSite: See Deployment Guide for Git MultiSite Plus. Integration with both (SVN and Git MultiSite): Running Access Control Plus in this mode enables combined management of Git and Subversion teams and resources. See both MultiSite deployment guides. Standalone mode In standalone mode only Access Control data is replicated between nodes. Each Access Control Plus node only manages access to local repository data. Generated password/Authz files are stored directly on the Access Control nodes. Standalone mode is available for SVN only Currently the Standalone mode is not able to support Git.
Git or SVN clients	Any that are compatible with Git or SVN servers.
Apache server	You will need to configure an Apache server to handle repositories appropriately. See specific Git and SVN details in the corresponding guides: Git MultiSite Authentication (HTTP) SVN MultiSite Deployment Checklist (Apache)
SSH for Git or SVN	SSH authentication is supported by Git MultiSite and SVN MultiSite. To use SSH for both Git and SVN use two accounts Make sure that you install Git MultiSite using one account and install Subversion MultiSite using a different account. Do this because the `~account/.ssh/authorized_keys` file can only point to either of Git or SVN. It is easy to set up and is attached to a service that is often already enabled. Occasionally, firewall rules may block clients. This is not as popular with Windows users: See how to set up SSH for Git in WANdisco Git MultiSite Administrator's Guide See how to set up SSH for SVN in WANdisco SVN MultiSite User Guide Audit accounts need administrator to change SSH key settings! Currently, only administrators can update or delete an audit account SSH key. A future release will enable audit account self-service options.
System memory	Ensure RAM and swapping containers are at least four times larger than the largest repository file. Minimum: 2GB RAM; 4GB swapping container Note: We do not recommend using the minimum By default, Access Control Plus's Java process is allocated the following heap space: -Xms128m -Xmx2048m In case of problems getting Access Control Plus running, you may need to alter the heap. If you need to reduce the heap size you won't be operating with a comfortable margin: consider increasing your server's system memory. Recommended: 4GB; 4GB swapping container Running with other apps: In production you must always ensure that your system operates with a comfortable margin. The above memory recommendations do not take into account other applications that you may run on the server, e.g. running Access Control Plus with either the Git or SVN MultiSite products. We recommend that you complete load testing and specify your server's memory based on peak usage.
Disk space	Subversion: Match to projects and branches. Checkouts: You need sufficient disk space to handle large, in-transit checkouts which may get buffered to a tmp directory beneath the replicator installation until that checkout has been completed. The required space can be calculated using the following guideline:
File descriptor limit	Ensure hard and soft limits are set to 64000 or higher. Check with the `ulimit` or `limit` command.
Journaling file system	Replicator logs should be on a journaling file system, for example, ext3 on Linux or VXFS from Veritas.
Maximum user process limit	At least three times the number of Git or SVN users.
Java	Install JDK 6 (previously referred to as 1.6) or higher. We recommend using Oracle JDK 6. JDK 7 Although we currently develop primarily to support Java 6's feature set, Access Control Plus is also compatible with Java 7.
Component compatibility	When upgrading Access Control Plus, Git MultiSite or Subversion MultiSite Plus, you must upgrade the Generic File Replication script to match your version of these products. We have tested ACP 1.0 (build 1266) and ACP 1.0.0.2 (build 6503) with ACP GFR 1.0 (build 1635) and MSP/GitMS 1.1 and earlier. Contact WANdisco Support to plan an upgrade to a later version. ACP 1.0.1 (build 1737) was tested with ACP GFR (build 1737) and MSP/GitMS 1.2* and 1.3.0, 1.3.1.
License model	See License Management.

2. Deployment types

You can deploy Access Control Plus in various modes, including:

Standalone: One or more nodes that handle repository access control within a non-replicated SCM environment. I.e. Access Control Plus can still be replicated between multiple nodes. "Standalone" indicates that it is not dealing with replicated Git or SVN data.
With Git MultiSite: One or more nodes deployed at one or more sites in conjunction with WANdisco's Git MultiSite product.
With SVN MultiSite: One or more nodes deployed at one or more sites in conjunction with WANdisco's SVN MultiSite product.
Both (with Git & SVN MultiSite): One or more nodes deployed at one or more sites in conjunction with both of WANdisco's SCM replication products.

After installation you can see which mode you're in: Check your mode

3. Install Access Control Plus

When you've checked through the deployment checklist and you're confident that your system meets all the requirements, follow the steps in this section to install Access Control Plus.

Don't forget to check the Release Notes for the current version. They may refer to known limitations that affect you. See Release Notes

Tip
If you have problems, see the information on our Knowledgebase before contacting Support.

Download the Access Control Plus installation script scm-access-control-plus_rpm_installer.sh from the WANdisco File Distribution website, plus the necessary license key.
Create a home directory for the installation, e.g. /opt/wandisco.
Ensure that the license.key file is placed on your server. You need to provide a path to it during installation. Before you start, make sure the license matches the version of Access Control that you need.
Ensure that the installation script is executable, e.g., enter the command:
```
chmod a+x scm-access-control-plus_rpm_installer.sh 
```

Run the installation script.

Running Apache?
Run Access Control Plus with the same user and group that is used for Apache. This will help prevent permission problems.

Non-interactive installation You can complete an installation without user interaction. See Non-interactive installation.

[root@redhat6 wandisco]# ./scm-access-control-plus_rpm_installer.sh
Verifying archive integrity... All good.
Uncompressing WANdisco Access Control Plus..........

    ::   ::  ::     #     #   ##    ####  ######   #   #####   #####   #####
   :::: :::: :::    #     #  #  #  ##  ## #     #  #  #     # #     # #     #
  ::::::::::: :::   #  #  # #    # #    # #     #  #  #       #       #     #
 ::::::::::::: :::  # # # # #    # #    # #     #  #   #####  #       #     #
  ::::::::::: :::   # # # # #    # #    # #     #  #        # #       #     #
   :::: :::: :::    ##   ##  #  ## #    # #     #  #  #     # #     # #     #
    ::   ::  ::     #     #   ## # #    # ######   #   #####   #####   #####




Welcome to the WANdisco Access Control Plus installation

You are about to install WANdisco Access Control Plus version 1.0.0-1229

Do you want to continue with the installation? (Y/n) Y

Enter Y to continue. The installer checks for prerequisite applications.
If there's a problem with Java, recheck the deployment checklist for information about their requirement. When Java is confirmed as installed, heap settings are applied for running Access Control Plus.
```
Checking prerequisites:

INFO: Using the following Memory settings:

INFO: -Xms128m -Xmx2048m

Do you want to use these settings for the installation? (Y/n) Y
      
```
Use the default settings and enter Y. For production, match these settings to your requirements. In this case, enter N and type in the start and maximum heap values.
Changing Java heap after installation
The Java heap settings are stored in the configuration file /opt/wandisco/scn-access-control-plus/main.config, e.g:
```
# Access Control Plus configuration
# DO NOT DELETE
ACP_USER=wandisco
ACP_GROUP=wandisco
ACP_MEM_LOW=128
ACP_MEM_HIGH=2048
      	
```
Setting the LOG_FILE environmental variable
If you need to capture a complete record of installer messages, warnings, errors, then you need to set the LOG_FILE environment variable before running the installer.
Run:
```
export LOG_FILE="opt/wandiscoscp/log/file.file"
```
This file's permissions must allow being appended to by the installer. Ideally, the file should not already exist (or it should exist and be empty) and its directory should enable the account running the installer to create the file.
The installer confirms TCP ports that it requires:
```
Which port should ACP listen on? [8082]: 8082
Which port should DConE listen on? [6444]: 6444
Which port should the Content Delivery service listen on? [6445]: 6445
      
```
You can use the default values. However, we strongly recommend that you allocate ports as part of a detailed site survey so that you can be sure that there are no conflicts and that all required ports are available on all sites.

Enter the path to your license.key file, then press Enter:

A license file is required to use Access Control Plus

Path to the license file: /opt/wandisco/license.key

Enter a name for the Access Control Plus Node. This is used to refer to this particular instance of Access Control Plus. Choose a unique name consisting of numbers and letters:
```
Node name: node70
```
Enter system user and group details for running Access Control Plus. Note the warning about not using root user. In this case we've created a specific user and group to use with our SCM-related services and applications:
```
We strongly advise against running Access Control Plus as the root user.

Which user should Access Control Plus run as? wandisco

Which group should Access Control Plus run as? wandisco	
      
```
The next option configures the node for operating as part of a replication group. If you are installing a single Access Control Plus node, select Y. If you are installing multiple Access Control Plus nodes for replication, you need to decide which nodes will have this option enabled:
```
One of your Access Control Plus nodes needs to be configured as a state machine creator. This MUST only be configured on ONE node.

Configure this node as the statemachine creator? (y/N) y
      
```
We entered y. If you're installing multiple Access Control Nodes then select enter y for just one of them.

Enter the details for an administrator account. You use these details to access the Access Control admin console:

Access Control Plus needs an admin user to be configured

First Name: Adie
Last Name: Ministrator
Username: admin
Email Address: adie@theorganization.com
Enter a password for admin:
Confirm the password for admin:

You are given a summary of your entries. Check them and enter y if you are happy to continue:

Installing with the following settings:

System user:                 wandisco
System group:                wandisco
Node name:                   node70
Application Port:            8082
DConE Port:                  6444
Content Delivery Port:       6445
Application Hostname:        10.0.5.96
License:                     /opt/wandisco/license.key
Admin user:                  admin
Application Minimum memory:  128
Application Maximum memory:  2048
Statemachine Creator:        true

Do you want to continue with the installation? (Y/n) y

The installation completes and confirms a restart:
```
Restarting scm-access-control-plus services...
Stopping scm-access-control-plus:[  OK  ]
Starting scm-access-control-plus:[  OK  ]
Installation Complete
[root@redhat6 wandisco]#
      
```
At this point the Access Control Plus is running. Open a browser and point it at http://<serviceIP>:8082/ui.
If you chose a different application port earlier in the process then you need to use it instead of the default "8082".

Include /ui/ from the URL
The browser-based admin console requires that you include the /ui/ directory in its URL. A future release will ensure that any request on the application port will redirect to the admin console.
You are presented with the Access Control Plus End-user Agreement. Read through the agreement, then click Accept to continue.
Log in for the first time. Enter the username and password that you provided earlier. Then click Let's do this

You see Access Control Plus's Management Screen. This summarises the accounts, teams and SCM repositories that Access Control Plus manages, and rules that dictate the SCM resources that account holders can access.

4. Setting up

After installing you need to set up Access Control Plus to work to your deployment requirements. Different deployments require different steps. Below are checklists for some example deployments.

4.1 Standalone mode

In Standalone mode there's no integration with an SCM replication product (e.g. Git MultiSite).

In this example you run with multiple Access Control Plus nodes, using LDAP authentication and SSL end-to-end encryption of traffic. Click each step to be taken to the relevant sections. Ignore or replace steps that aren't required. For example, if you are not running with LDAP, you might replace that step with Adding Accounts.

Follow the links in these steps if you are deploying in Standalone mode:

Induction: Connecting your nodes
LDAP: Enable LDAP Auth
SSL: Enable SSL encryption
Email notifications: Set up email notification
Repositories templates: Create repositories templates
Resources: Add resources
Teams: Create a team
Rules: Create a rule

If you are running with only one Access Control node, you can drop the Induction step.

4.2 Access Control Plus with MultiSite

Follow the links in these steps if your are deploying with a MultiSite product:

Induction: Connecting your nodes
Git/SVN MultiSite: Connect to MultiSite
LDAP: Enable LDAP Auth
SSL: Enable SSL encryption
Email Notifications: Setup Email notification
Repositories Templates: Create repositories templates
Resources: Add resources
Teams: Create a team
Rules: Create a rule

Access Control Plus is now installed. Before you start setting up accounts, teams, etc. you should run through the Settings screen. First, check off what other elements on your platform need to be integrated into Access Control Plus.

4.3 Setting up LDAP

It is common practice to use one or more LDAP authorities for managing which employees need accounts created in Access Control Plus. You connect any number of LDAP authorities, adding them through the Settings screen.

Local users are exempt from updates and removal for synchronization of team admins and team members. This means that a local admin who appears in an authority won't suddenly be added to a team or be made into a sys admin. Instead a message is logged to indicate that this user has been skipped. The sys admin must then ensure that the local user is removed.

4.4 Access control settings

1. From the admin console, click the Settings link on the menu bar.
Settings 01

2. The settings are displayed in an accordion-style menu. Click either the links on the side menu or the title bars in the right-hand panel.
Settings 01

Full details on setting up each section are provided in the Settings reference guide. Apply settings suitable for your deployment of Access Control Plus. The product's appearance and functionality differs depending on whether you are running it in a standalone mode or in conjunction with WANdisco's Git or SVN MultiSite products.

4.5 Application Settings

These settings extend Access Control Plus's functionality:

Access Control Updates: This option contains settings for running Access Control in Batch updates mode. For more information see the reference section on Batch updates.
Repository Templates: This option defines Git or SVN repositories. For Access Control Plus to manage access to a repository, you must add a template that corresponds with an existing repository, along with appropriate references to a password or authorization file.
See Adding repository templates, Managing Repository Templates.

4.6 Node Management

These settings control how Access Control Plus communicates with other Access Control Plus nodes on the replication network, specifically when Access Control Plus is used with WANdisco's DConE replication protocol.

Node Induction: The Node Induction option describes how to connect this particular instance of Access Control Plus to a replication network. Again, this applies to deployments where multiple instances of Access Control Plus are running, which would allow each development site to have its own replica of the access control service. See Inducting a node.
Node Repairs: Use this option if one or more nodes are lost or experiencing a lengthy disconnection from the replication network. This redefines the replication group so that the remaining nodes can continue to operate. See Running a node repair.

4.7 External Applications

These connect Access Control Plus to supporting systems for additonal functionality.

Connect to MultiSite: If you are running Access Control Plus with WANdisco's Git or SVN MultiSite products then you need to enter the necessary details for Access Control Plus to talk to MultiSite via its REST API interface. See Connecting to SVN MultiSite and Connecting to Git MultiSite.
Connect to LDAP: Most deployments use an existing LDAP authority to manage their employee system accounts. This option lets you connect to multiple LDAP authorities and set up queries to filter for accounts that need access to SCM resources. See Adding an LDAP Authority, Manage LDAP Authorities.
Email Notifications: Set the Email Notifcations to connect to an available relay server so that Access Control Plus can send notifcation emails to administration staff.
See Enable email notifcations and Manage email settings.

5. Non-interactive installation

You can start installing a node without root-level terminal access to the server, known as a silent installation. When the installation has finished you can complete the configuration of the node through a browser (interactive-style) or script the configuration using REST API calls. Note, however, that induction of the nodes still requires interaction with the admin UI.

For a silent installation run:

ACP__USER=wandisco
ACP_GROUP=wandisco
ACP_PORT=9000
etc...
export ACP_USER ACP_GROUP ACP_PORT ACP_DCONE_PORT ACP_CONTENT_PORT ACP_NODE_NAME etc...
./scm-access-control-plus_rpm_installer.sh

The installation then runs without user interaction. When completed, the browser-based admin console starts. You then need to complete the node setup from the restart stage.

You should be able to build additional automation into the installation by using various calls to the REST API, e.g. setting up an admin account, setting up defaults for resources, templates and LDAP settings, etc. However, you cannot yet complete the induction of nodes without support from WANdisco's support team.

Environmental variables used are:
ACP_USER=wandisco: System user for the Access Control Plus process
ACP_GROUP=wandisco: System group used by Access Control Plus process
ACP_PORT=9000: Port allocated for web access to the admin console
ACP_DCONE_PORT=9050: Port allocated for replicated data
ACP_CONTENT_PORT=8000: Port allocated for Access Control's internal content delivery
ACP_NODE_NAME=node1: Name of the Node which is different for each node
ACP_ADMIN_USER=admin: Admin account username
ACP_ADMIN_FIRST_NAME=mr: Admin account first name
ACP_ADMIN_LAST_NAME=admin: Admin account last name
ACP_ADMIN_EMAIL=mr@admin.com: Email address for the admin account - needed to allow Access Control Plus to send out notification emails
ACP_ADMIN_PASSWORD=password: Admin password
ACP_MEM_LOW=128: The minimum amount of memory allocated to Access Control Plus
ACP_MEM_HIGH=2048: The maximum amount of memory allocated to Access Control Plus
ACP_LICENSE_FILE=/home/wandisco/keys/License.key: The full path to the license.key file
ACP_STATEMACHINE_CREATOR='true': True only for a single (induction controller) node, false for the rest
ACP_HOSTNAME=node1: The IP address or fully qualified domain name of the node which must match with those encoded into to the license.key file