Server administration basics

This topic describes the items that the StarTeam admin should know in order to effectively administer the product.

StarTeam Server administration overview

StarTeam is a software change and configuration management solution designed to meet the needs of local and distributed teams,regardless of their size and work style.

The StarTeam Server manages data for all its client applications. It is maintained by an administrator who is familiar with the complexities and details of the its operation. Client applications, such as the Cross-Platform Client, connect to the StarTeam Server to access data.

This guide assumes that StarTeam Server administrators are familiar with:

Creating and modifying relational databases.
Working with the features of their operating system, such as creating files, running executable files, and managing access rights.
Basic software configuration management concepts.

Caution: StarTeam Server administrators must never modify database contents or vault files other than through a client or Server Administration tool. Direct database manipulation is not supported.

Server administrator tasks

As an administrator who initially installs the StarTeam Server, you may perform some or all of the following actions:

Install the StarTeam Server
Configure the StarTeam Server
Register (license) the StarTeam Server
Create and start a new StarTeam Server configuration (an instance of the StarTeam Server)
Add new users and groups to the StarTeam Server configuration.
Set up Directory Server and add LDAP users.
Set up a password policy for non-LDAP users.
Create projects and views for the StarTeam Server configuration.
Set up access rights for projects.
Enable StarTeam Server configuration diagnostics.
Set up email notification and customize automatic email notification with your own text or HTML-based email message templates.
Set up system policy, that is, manage passwords, logon failures, access rights, and security events for the server configuration.

The StarTeam Server creates new projects with only the File type pre-selected as a default for new views. Users can still change the project properties after the project is created, and they can change the item types included for any given new view. However, if the user changes nothing, by default new views will only include files when they are created.

A StarTeam Server can manage any number of projects. Each project has one root view and any number of child views. The root view and every child view has one application folder as a root folder. An application root folder can have any hierarchy of child folders. This is called the folder hierarchy. When an administrator creates a project, that project’s root view and the root view’s root folder are created automatically and given the same name as the project. For example, if the project’s name is Great App, the root view’s name is initially Great App, and the root folder’s name is initially Great App (although the administrator can change these names).

Your first task as an administrator is to install, configure, and register the StarTeam Server, as explained in the StarTeam Installation Guide. Next, you must create an instance (known as a StarTeam Server configuration) on the computer on which the StarTeam Server is installed. A StarTeam Server configuration must be running before you and your team members can access the application.

Architectural overview

The standard StarTeam architecture represents the minimal components present in a StarTeam instance: a StarTeam Server process managing a vault and a database and one or more StarTeam clients. With just these components, all basic StarTeam functionality is available. The core components of the standard StarTeam architecture are shown below.

StarTeam employs a client/server architecture. The StarTeam Cross-Platform Client, Server Administration tool, and StarTeam Command Line Tools are examples of bundled StarTeam clients. StarTeam clients use the freely available StarTeam SDK, so you can write custom applications that have access to the same features as the bundled clients. The SDK is fully featured in Java, .NET, and COM, allowing you to write custom applications for any environment. A single StarTeam client can have multiple sessions to any number of StarTeam Servers.

All StarTeam clients connect to a StarTeam Server process using TCP/IP, so virtually any kind of network can be used: LAN, WAN, VPN, or the public Internet. StarTeam uses a proprietary protocol called the command API, which supports compression and multiple levels of encryption. The command API has been optimized to support high performance, automatic reconnect, delta check-out for slow connections, and other important features.

A single deployment instance of StarTeam is known as a server configuration, usually shortened to just configuration. The persistent data of a configuration consists of a database and a vault and is managed by a single StarTeam Server process. The database holds all metadata and non-file artifacts, whereas file contents are stored in the vault. The database can be any of the supported databases and it can reside on the same machine as the StarTeam Server process or a separate machine. The StarTeam database and vault can be backed-up dynamically, while the server is in use. This supports 24 x 7 operations that want to minimize down time.

StarTeam’s vault is a critical component that affects performance and scalability. In contrast to the traditional delta storage technique, StarTeam’s vault uses an innovative architecture designed for scalability, performance, high availability, and dynamic expandability. Today, customers are storing up to a terabyte of data in a single StarTeam vault, but it was designed to store content up to a petabyte and beyond.

Within the vault, files are stored in containers known as hives. A hive is a folder tree containing archive and cache files on a single disk volume. Hives can be dynamically added on existing or new disk volumes, thereby allowing virtually unlimited capacity. StarTeam stores each file revision in a separate archive file in a manner that minimizes space usage as well as duplicate content. StarTeam’s vault uses less space than delta-based storage. In certain cases where it is more economical to send file deltas to clients instead of full versions, StarTeam generates and caches delta files. However, in most cases sending full versions is more economical.

Source control basics

Each source control system consists of one or more centralized repositories and a number of clients. A repository is a database that contains not only the actual data files, but also the structure of each project you define.

Most source control systems adhere to a concept of a logical project, within which files are stored, usually in one or more tree directory structures. A source control system project might contain one or many IDE-based projects in addition to other documents and artifacts. The system also enforces its own user authentication or, very often, takes advantage of the authentication provided by the underlying operating system. Doing so allows the source control system to maintain an audit trail or snapshot of updates to each file. By storing only the differences, the source control system can keep track of all changes with minimal storage requirements. When you want to see a complete copy of your file, the system performs a merge of the differences and presents you with a unified view. At the physical level, these differences are kept in separate files until you are ready to permanently merge your updates, at which time you can perform a commit action.

This approach allows you and other team members to work in parallel, simultaneously writing code for multiple shared projects, without the danger of an individual team member's code changes overwriting another's. Source control systems, in their most basic form, protect you from code conflicts and loss of early sources. Most source control systems give you the tools to manage code files with check-in and check-out capabilities, conflict reconciliation, and reporting capabilities. Most systems do not include logic conflict reconciliation or build management capabilities.

Commonly, source control systems only allow you to compare and merge revisions for text-based files, such as source code files, HTML documents, and XML documents. StarTeam stores binary files, such as images or compiled code, in the projects you place under control. You cannot, however, compare or merge revisions of binary files. If you need to do more than store and retrieve specific revisions of these types of files, you might consider creating a manual system to keep track of the changes made to such files.

Repository basics

Source control systems store copies of source files and difference files in some form of database repository. In some systems, such as CVS or VSS, the repository is a logical structure that consists of a set of flat files and control files. In other systems, such as StarTeam, the repositories are instances of a particular database management system (DBMS).

Repositories are typically stored on a remote server, which allows multiple users to connect, check files in and out, and perform other management tasks simultaneously.

With StarTeam, you create a server configuration to identify a repository for StarTeam projects. Each server configuration acquires its own set of projects as they are created. The Server can run any number of server configurations. Because each server configuration must use a database, you need to make sure that you establish connectivity not only with the server, but also with the database instance.

Check-ins

All check-ins in StarTeam are atomic. Whenever more than one file is checked in as the result of a single transaction all of the files, and their associated process items, are updated in a single action. If for some reason, the check-in fails, none of the files are checked in, and the status of the associated process items is not updated.

For example, suppose User A selects to check in all modified files in a StarTeam folder, but one of the selected files is locked by User B. Because of the locked file, none of the files are checked in (and none of the process items are updated as fixed) and User A is notified that none of the files were checked in because one of the files was locked by User B.

Sample configuration data

StarTeam provides sample configuration data that you can download from within the Server Administration tool. It contains a Visual C++ sample application and related materials. It has sample files, change requests, topics, tasks, and it also includes a StarFlow Extension project. You can use the sample repository to experiment with and learn more about StarTeam.

The StarTeam Server creates new projects with only the file type pre-selected as a default for new views. You can change the project properties after the project is created, and change the item types included for any given new view. However, if you do not change anything, by default new views will only include files when they are created.