Server Requirements

To install the Deployit server, the following prerequisites must be met:

• Operating system: Windows or Unix-family operating system running Java.
• Java Runtime Environment: JDK 1.6 (Sun/IBM or Apple)
• RAM: At least 2GB of RAM available for Deployit.
• Harddisk space: Sufficient harddisk space to store the Deployit repository. This depends on your usage of Deployit. See section Determining Harddisk Space Requirements.

Depending on the intended usage of Deployit, the following may also be required:

• Database: Deployit's Jackrabbit repository supports a number of different databases. For more information see Jackrabbit's persistence manager FAQ.
• LDAP: To enable group based security, an LDAP x.509 compliant registry is needed.

Determining Harddisk Space Requirements

The amount of diskspace Deployit uses is dependent on how the product is used in your environment. It is most influenced by:

• the size and storage mechanism used for artifacts
• the number of packages in the system
• the number of deployments performed (more specifically, the amount of logging information stored)

To obtain an estimate, do the following:

• Install and configure Deployit for your environment as described in this document. Make sure you correctly set up the database-based or file-based repository.
• Estimate the number of packages to be imported (either the total number or the number per unit of time) (NumPackages)
• Estimate the number of deployments to be performed (either the total number or the number per unit of time) (NumDeployments)
• Record the amount of diskspace used by Deployit (InitialSize).
• Import a few packages using the GUI or CLI.
• Record the amount of displace used by Deployit (SizeAfterImport).
• Perform a few deployments.
• Record the amount of displace used by Deployit (SizeAfterDeployments).

The needed amount of diskspace in total is equal to:

Space Needed = ((SizeAfterImport - InitialSize) * NumPackages) +
    ((SizeAfterDeployments - SizeAfterImport) * NumDeployments)

If NumPackages and NumDeployments are expressed per timeunit (e.g. the number of packages to be imported per month), then the end result represents the space needed per month as well.

Unix Middleware Server Requirements

Unix-based middleware servers that Deployit interacts with must meet the following requirements:

• SSH Access: The target systems should be accessible by SSH, i.e. they should run an SSH2 server. ¹²
• Credentials: Deployit should be able to log in to the target systems using a login/password combination that allows it to perform at least the following Unix commands:
  • cp
  • ls
  • mv
  • rm
  • mkdir
  • rmdir
  If the login user cannot perform these actions, a sudo user may be selected that can execute these commands.

Windows Middleware Server Requirements

Windows-based middleware servers that Deployit interacts with must meet the following requirements:

• CIFS/Telnet: The target system should be accessible using Windows Telnet server running in stream mode. ³
• Directory shares: The account used to access a target system should have access to the host's administrative shares such as C$.

Client Requirements

The clients that access Deployit must meet the following requirements:

• Web browser: The following web browsers are supported:
  • IE 7.0 or up
  • Firefox 3.0 or up
  • Safari 3.0 or up
• Flash Player: A flash player is required, versions 9.0 and up are supported.

Installing the Server

Follow these steps to install the Deployit server application:

1. Login to the server where Deployit will be installed. The recommended way to install Deployit is to use a non-root user.
2. Create an installation directory.
3. Copy the Deployit release distribution to the directory.
4. Unzip the release into the created directory.

Deployit Directory Structure

Once the Deployit installation file is extracted, the following directory structure exists in the Deployit installation directory (in the remainder of the document this directory will be referred to as DEPLOYIT_HOME):

• bin: contains the server binaries
• cli: contains the client application, including binaries and libraries
• doc: contains the documentation
• importablePackages: default location for importable packages
• lib: contains server libraries
• plugins: contains the Deployit middleware plugins
• recovery.dat: stores tasks that are in progress for recovery purposes

Running the Setup Wizard

Run the Deployit Setup Wizard to start the Deployit server and make it ready for use. The command deployit.sh -setup starts the wizard. If you want to stop the Setup Wizard at any time, enter exitsetup. All changes to the configuration will be discarded.

The Setup Wizard displays the following welcome message:

Welcome to the Deployit setup.
You can always exit by typing 'exitsetup'.
To re-run this setup and make changes to the Deployit server configuration 
you can run deployit.cmd -setup on Windows or deployit.sh -setup on Unix.

Do you want to use the simple setup?
Default values are used for all properties. To make changes to the default 
properties, please answer no.
Options are yes or no.
[yes]: 

Answer yes (or press Enter) to use the simple setup. Simple setup makes it easy to quickly get started with Deployit and to use the product's default configuration. See Simple Setup for more information.

Answer no to use the manual setup. Manual setup provides explicit control over all Deployit settings. See Manual Setup for more information.

Note: if you installed Deployit in the same location before, the Setup Wizard will display the following message:

An existing configuration was found. Do you want to edit it?
Options are yes or no. (selecting no will create an empty configuration)
[yes]: 

Answer yes (or press Enter) to edit the existing configuration. The Setup Wizard will load all settings from the existing configuration and allow you to choose simple or manual setup.

Answer no to start over with an empty configuration.

Do you want Deployit to initialize the JCR repository?
Options are yes or no.
[yes]: 

Would you like to enable SSL?
Options are yes or no.
[yes]: 

Would you like Deployit to generate a keystore with a self-signed 
certificate for you?
N.B.: Self-signed certificates do not work correctly with some versions 
of the Flash Player and some browsers!
Options are yes or no.
[yes]: 

What is the path to the keystore?
[]: 

What is the password to the keystore?
[]: 

What is the password to the key in the keystore?
[]: 

What http port number would you like the server to listen on?
[4516]: 

Enter the minimum number of threads the HTTP server should use (recommended: 
    3 per client, so 3 for single user usage)
[3]: 

Enter the maximum number of threads the HTTP server should use (recommended :
    3 per client, so 24 for 8 concurrent users)
[24]: 

Where would you like Deployit to store the JCR repository?
[repository]: 

Do you want Deployit to initialize the JCR repository?
Options are yes or no.
[yes]: 

Where would you like Deployit to import packages from?
[importablePackages]: 

Do you agree with the following settings for Deployit and would you like 
    to save them?
Changes will be saved in deployit.conf
    Security is always enabled
    SSL will be disabled
    HTTP port is 4516
    HTTP server will use a minimum of 3 and a maximum of 24 threads
    JCR repository home is at repository
    JCR repository will be initialized.
    Task recovery file will deleted
    Application import location is importablePackages
[yes]:         

You can now start your Deployit server by executing the command deployit.cmd 
    on Windows or deployit.sh on Unix.
Note: If your Deployit server is running please restart it.
Finished setup.

Changing the Admin Password

By default, Deployit is installed with a special user with administrative permissions. This user has the username admin and password admin. As the last step in the installation, the admin password should be changed to something more secure. Issue the following commands to do this:

adminUser = security.read('admin')
adminUser.password = 'newpassword'
security.modifyUser(devUser)

# Test whether the change is successful
security.logout()
security.login('admin', 'newpassword')

Security in Deployit

Deployit supports a fine-grained access control scheme to ensure the security of your middleware and deployments. Deployit's security mechanism is based on the concepts of principals, permissions and privileges.

Principals

A (security) principal is an entity that can be authenticated and that can be assigned rights over resources in Deployit. Out of the box, Deployit supports only users as principals -- users are authenticated by means of a username and password and rights within Deployit are assigned to the user itself. When using an LDAP repository, groups in LDAP are also treated as principals.

There is one special user, admin, who has special rights in Deployit. This user is allowed to grant and revoke security permissions.

Permissions

Permissions in Deployit are rights to execute particular actions on certain CIs. In addition, the permissions also allow the user to make changes to the repository that are necessary to carry out the granted actions. If granting the permission without specifying the target CI(s), broad repository access is allowed. See the list below.

Deployit supports the following permissions:

• read. The right to see particular CIs.
• login. The right to log into the Deployit application. The user has no access to nodes in the repository.
• import#initial. The right to import a package for which the application does not yet exist in the repository and for which a new application will be created. This implies read and write access to the Applications node. The permission can also be given for specific Application CIs.
• import#upgrade. The right to import a package for which the application already exists in the repository. This implies read and write access to the Applications node. The permission can also be given for specific Application CIs.
• deploy#initial. The right to perform an initial deployment of a package to an environment. This implies read and write access to the Environments and Infrastructure nodes. The permission can also be given for specific Environment CIs.
• deploy#upgrade. The right to perform an upgrade of a package on an environment. This implies read and write access to the Environments and Infrastructure nodes. The permission can also be given for specific Environment CIs.
• discovery. The right to perform discovery. This implies read and write access to the Infrastructure node.
• repo#edit. The right to edit (create and modify) CIs. This implies write access to the Applications, Environments and Infrastructure nodes. The user must also have read access to CIs to be able to edit them. The permission can also be given for specific CIs.
• undeploy. The right to undeploy an application. This implies read and write access to the Environments and Infrastructure nodes. The permission can also be given for specific Environment CIs.

Granting, Revoking and Denying

Access rights in Deployit can be granted to a principal or revoked from a principal. When rights are granted, the principal is allowed to perform some action or access repository entities. Rights once granted can be revoked again to prevent the action in the future. Rights can also be explicitly denied. Denying permission acts as a negative grant -- the right is explicitly disallowed.

Access rights can be used stand-alone or in combination with one or more CIs. In the former case, the principal will have access to all CIs associated with the permission. In the latter case, the access rights will be restricted to the particular CIs. For example, granting import#initial to a principal allows the principal to import any application. Granting import#initial to Applications/PetClinic allows the principal to import only PetClinic packages.

Configuring Repository Security

Security in the Deployit repository can be configured using the Command Line Interface. See the Deployit Command Line Manual for more information.

Creating Users

Deployit can only create users in it's own repository, even if it is configured to use an LDAP repository for authentication and authorization. To do this, use a statement such as the following:

deployer = security.createUser("john", "secret")

Granting Permissions

To grant a particular permission to a principal, use a statement such as the following:

security.grant("import#initial", "john")

To grant a particular permission to a principal on a resource, use a statement such as the following:

security.grant("read", "mary", ['Environments/Dev'])

Revoking Permissions and Privileges

To revoke a particular permission from a principal, use a statement such as the following:

security.revoke("read", "john", ['Environments/Dev'])

Inherited Permissions

Permissions in Deployit are inherited for all CIs that are contained in the CI node you specified the permissions for. For example, if you have read permission on Environments/Dev, you will also have read permission on all of the CIs under this node such as deployed applications. This is what happens when you use stand-alone permissions. If you use permissions on specific CIs, these permissions are set only on the specified CIs and are inherited from this CI onwards.

Permissions on Deployed Applications###

Giving users permissions on deployed applications requires some knowledge of how these CIs are stored in the repository. As described in the Deployit Reference Manual, deployed applications are stored under both the /Environments as well as /Infrastructure nodes. Giving users read permission on a deployed application involves giving them permissions under both nodes.

Security Configuration Example

Let's illustrate the security setup with an example.

In a typical medium to large size company, there several different groups of people that perform tasks related to deployments. There are administrators that install, test and maintain hardware, there are deployers that deploy applications to development, test, acceptance and production environments. And finally there are the developer who build these applications.

Translating this into Deployit terms:

• administrators: permission to create, update and delete infrastructure as well as permission to create, update and delete environments. (all handled by _infrastructure#management permission)
• deployers: permission to import new applications (import#initial), deploy to DEV, TEST and view PROD (deploy#initial and deploy#upgrade on environments DEV and TEST, read rights on environment PROD).
• senior deployers: permission to import new applications (import#initial), deploy to DEV, TEST and PROD (deploy#initial and deploy#upgrade on environments DEV, TEST and PROD).
• developers: permission to import new versions of existing applications (import#upgrade) and to upgrade existing deployments (deploy#upgrade).

See the Deployit Command Line Interface (CLI) Manual for the exact commands to implement this.

Configuring LDAP Security

By default, Deployit authenticates users and retrieves authorization information from it's repository. Deployit can also be configured to use an LDAP repository to authenticate users and to retrieve role (group) membership. In this scenario, Deployit works with both users and groups as principals. This means that rights can be assigned to both users and groups. The rights assigned to a principal are always stored in the JCR repository.

Deployit treats the LDAP repository as read-only. This means that Deployit will use the information from the LDAP repository, but can not make changes to that information.

When authenticating a user, Deployit first tries to locate the user in the LDAP repository. If this fails, Deployit will check it's own repository as a backup.

To configure Deployit to use an LDAP repository, the built-in JCR repository, Jackrabbit, must defer to the LDAP server for authentication. This requires modification of the default Deployit Jackrabbit configuration. Follow these steps:

1. Create conf/jackrabbit_jaas.config file. The file must be accessible for the Deployit server. The following is a sample file:

   Jackrabbit {
       org.apache.jackrabbit.core.security.authentication.DefaultLoginModule 
           sufficient adminId=admin anonymousId=anonymous;
       com.xebialabs.deployit.security.LdapLoginModule required 
           userProvider="ldap://localhost:14516/ou=system" 
           userFilter="(&(uid={USERNAME})(objectClass=inetOrgPerson))" 
           useSSL=false
       principalProvider=com.xebialabs.deployit.security.LdapPrincipalProvider;
   };
   

   Modify the LDAP settings (URL, port or user filter, etc.) to suit your needs.

2. Modify the Deployit server startup command. Notify the Deployit server of the new configuration file by including the following parameter on the Java command line:

   -Djava.security.auth.login.config="$DEPLOYIT_HOME/conf/jackrabbit_jaas.config"
   

3. Extract the jackrabbit-repository.xml from the jar, and change it

   cd $DEPLOYIT_HOME/conf
   jar xvf ../lib/server-core-3.1.jar jackrabbit-repository.xml
   

   Change the jackrabbit-repository.xml by looking up the Security-block, and changing it to look like this:

   <Security appName="Jackrabbit">
       <SecurityManager class="org.apache.jackrabbit.core.DefaultSecurityManager" workspaceName="security" />
       <AccessManager class="org.apache.jackrabbit.core.security.DefaultAccessManager" />
   </Security>
   

The class LdapPrincipalProvider is an example of how to connect Deployit to LDAP through Jackrabbit. If your LDAP server has a different structure or to connect Jackrabbit to another user store, see the information about Jackrabbit configuration on the the Jackrabbit website.

Using a Database

Deployit can also use a database to store it's repository in. The built-in Jackrabit repository must be configured to make this possible. The two relevant components are Jackrabbit's PersistenceManager (used for storing nodes an d revisions) and DataStore (optionally used for storing large binary objects). In the default Deployit configuration, the Derby database and file system DataStore are used.

This is an example of how to configure Deployit to use a database.

First, extract the Jackrabbit configuration file and copy it to the conf directory where it will be picked up by Deployit:

cd $DEPLOYIT_HOME/conf
jar xvf ../bin/deployit-3.0-server.jar jackrabbit-repository.xml

Edit the Jackrabbit configuration file and change each PersistenceManager to the following:

MySQL ⁴.

<PersistenceManager class="org.apache.jackrabbit.core.persistence.pool.MySqlPersistenceManager">
    <param name="url" value="jdbc:mysql://localhost:3306/deployit" />
    <param name="user" value="deployit" />
    <param name="password" value="deployit" />
    <param name="schemaObjectPrefix" value="${wsp.name}_" />
</PersistenceManager>

DB2

Oracle

For more information about using a database with Jackrabbit, see it's PersistenceManager FAQ and DataStore FAQ.