This guide describes the procedures associated with Plastic SCM installation and maintenance.
This guide is targeted to developers and system administrators, assuming familiarity with Plastic SCM and operating system concepts.
Online documentation
Besides this and the rest of the guides, Plastic SCM provides online reference throughout its different client frontends.
On the command line interface, both Windows and Linux, this reference can be obtained with the command:
cm help
For extended information on a specific command, type:
cm help command
The graphical interface provides online reference through the Help menu.
Documentation errors
If you find any problem in this guide or any other part of the online reference, please notify it using the following email address:
1. Introduction
Plastic SCM is a Software Configuration Management system designed to handle software development teams of any size.
Plastic SCM provides high-end SCM capabilities but doesn’t impose any of the restrictions associated to these high-end systems like complex installation, operation and administration.
This guide assumes that the reader is familiar with the basic SCM concepts, with basic operating system usage through the command line and basic system administration.
The guide will show to both system administrators and SCM managers how to install the SCM system, how to create repositories, workspaces and how to make backups.
Plastic SCM uses a client / server architecture, divided into the following components:
· The server, responsible for storing all the project information, managing client access to that store.
· Clients run on the developers’ machines, and are responsible for communicating user operations to the server. Basic supported clients follow:
o Command Line Interface (CLI): gives access to Plastic SCM operations on the operating system shell. Very useful for task automation.
o Graphical User Interface (GUI): provides access to Plastic SCM operations using a window-oriented interface. It provides some graphical diagrams not available in the command line.
o Visual Studio integration: provides access to the most used operations like checkout / checkin from within the development environment, among a complete set of features.
o Eclipse integration: provides access to the most used operations like checkout / checkin from within the Eclipse development environment, among others.
o IntelliJ integration: provides acces to the most used operations in a version control system from the IDEA application.
o A big number of integrations with other kinds of software, like FinalBuilder, PowerBuilder, a big set of task controls, etc. Please, take a look to other manuals to get more information about this.
Figure 1: Structure and Plastic SCM's components
The following table shows the platforms supported for the system’s components:
|
Component |
MS Windows |
Linux |
Mac OS X |
|
Server |
X |
X |
X |
|
CLI client |
X |
X |
X |
|
GUI client |
X |
X |
X |
|
Visual Studio client |
X |
|
|
|
Eclipse client |
X |
X |
X |
Visit our web page in order to get a full list of compatibilities at www.codicesoftware.com.
2. Minimum requirements
Below you will find the minimum requirements, both hardware and software, needed to install and use Plastic SCM.
The minimum system requirements to run the Plastic server are:
· Windows 2000 Server, Windows 2000 Professional, Windows 2003 Server or Windows XP SP 2 Operating Systems. Server operating system strongly recommended.
· .NET Framework 2.0 or higher.
· 512 MB RAM.
· Enough free hard disk space. Hard disk space will vary depending on the size of project’s assets.
Client machine requirements will vary depending on the Plastic SCM client in use. The GUI or IDE integrations will have higher requirements than the command line one.
The supported operating systems are:
· Windows 2000 Professional or Windows 2000 Server.
· Windows 2003 Server.
· Windows XP SP2.
· Fedora
· Ubuntu
· RedHat
· Suse
· Debian
In all cases, the .NET Framework 2.0 (or mono 2.0 in the linux case) or higher is required.
The needed RAM will vary depending on:
· Command line client: is the thinner one and needs few resources to work. Nevertheless, as a general rule, a 512 Mb RAM machine is strongly recommended.
· GUI client: 512 MB RAM
· Visual Studio Plug-in: same requirements as the IDE.
· Eclipse Plug-in: same requirements as the IDE.
· Other integrations: same requirements as the program which Plastic integrates with.
3. Plastic SCM installation
One of the development team’s main goals is using a system which is easy to install, configure and use. With Plastic, installation is a straightforward process.
Plastic SCM server works as a Windows service. The service is registered and started (if start option is selected) during the installation process. So having enough permissions to register a new service is mandatory to make a successful installation.
Plastic SCM is distributed as a unique installation file. During installation it is possible to choose between server or client installation, or both, selecting the right options in the component list.
The installation steps are described in detail in Table 1.
|
Select the installation language |
Figure 2. Language selection |
|
Installer start screen |
Figure 3. Installer start up |
|
License agreement. Read the license carefully and click on accept if you accept the terms. |
Figure 4. License agreement |
|
Choose the installation directory. Select the directory in which Plastic SCM will be installed. Two subdirectories will be created inside this directory: one for the server and one for the client. |
Figure 5. Installation directory |
|
Component selection. Plastic SCM is divided into several components. In this screen user can choose the ones he needs to install on the machine. |
Figure 6. Component selection |
|
Ready to install. At this point the installer has all the information it requires to run. As no file or directory has been created on your disk, this is a good opportunity to abort the installation, if necessary. |
Figure 7. Ready to install |
|
File copy progress.
|
Figure 8. Copying files |
|
System configuration. Once the installation has been completed, the installer will launch, if the user selects the options, the different configuration programs. |
Figure 9. Start system configuration |
Table 1. Installation steps
The server configuration wizard can be started at the last step of the installer, or from Plastic SCM start menu entry.
|
Server configuration start up screen. |
Figure 10. Server configuration welcome screen |
|
Select the server’s language. It will be used for the log messages or errors. Clients and server can have different languages. Clients will get messages localized in their own configured language. |
Figure 11. Server configuration language selection |
|
Authentication mechanism. This is the most important step in the server configuration wizard. Here you have to choose between the different authentications mechanisms available. By default local users is selected. A detailed explanation about security modes is done at 3.4. |
Figure 12. Server configuration authentication modes |
|
If you choose the LDAP user security mode, you will have to fill in some more parameters. You have to specify the LDAP server name, and the domain from which data must be retrieved. Also a username and a password to be used to access the LDAP server. Finally choose whether the LDAP server is a conventional LDAP one or an Active Directory. |
Figure 13. LDAP Authentication configuration |
|
The last step is configuring the server’s port number. A default port is proposed. Remember that if you change the server’s port, you will need to install the clients setting this new port. |
Figure 14. Port configuration |
Table 2. Server configuration
Five authentication mechanisms are available:
· Local users
· Local users (Name + ID)
· Active Directory integrated security
· LDAP authentication
· User – Password
Each of them allows different authentication possibilities and will be detailed in the following sections.
3.4.1. Authentication basics
Client communicates certain security information to the server in order to be validated. The basic token sent from client to server is called SEID, the short name for SEcurity IDentifier.
The mechanisms to be described are basically based on different ways to build the SEID plus different ways to obtain users.
3.4.2. Local users
Local users means the Plastic SCM server will read the local users names from the machine it is running on. So on startup it will create a list of known users, and recalculate it periodically.
For the system to work correctly the clients must also be configured using the Local Users mechanism.
The client will take the name of its logged on user and send it to the server. This is the name that the server will use to first check whether it is a known user, and then make security calculations with.
This system heavily resides on correct network configuration. If a network is misconfigured it can have security flaws and it would be possible to cheat the server with identity hijacking.
It can be used on secured networks to easily configure a mixed Unix / Windows environment, relying, for instance on a NIS+ system.
It can also be used for easily configuring access from the Internet, provided that the server only allows trusted clients to connect.
|
How does the server obtain the user list? |
It retrieves it from the local machine users (both Unix and Windows operating systems). For Windows machines inside a domain it will take the current user if it’s not a local user. |
|
How is the SEID built? |
Just with the user name. |
3.4.3. Local users: name + ID
The mechanism is identical to local users but the SEID is built using both the user name plus the user ID.
It is a very simple way to prevent, or at least complicate a bit further, identity hijacking.
Under Windows systems the ID will be the SID of the user.
Under Unix based systems it will be the user id.
It works perfectly on non-cross-platform environments (Unix-Unix or Windows-Windows) but it will obviously break under Windows-Unix platforms unless a specific authentication mechanism is in place.
It can be used to work under NIS+ systems on Unix, or under any other configuration provided that both systems share the same user name and ID.
|
How does the server obtain the user list? |
It retrieves it from the local machine users (both Unix and Windows operating systems). For Windows machines inside a domain it will take the current user if it’s not a local user. |
|
How is the SEID built? |
User name + ID: user id on Linux and SID on Windows. |
3.4.4. Active Directory Integrated Security
Using this configuration mechanism user list will be retrieved from the current active directory server. This system needs the server to be running inside an operating system that can be part of an Active Directory. It is designed to be run on Windows based operating systems.
|
How does the server obtain the user list? |
It retrieves it from the active directory main server. The server must be correctly configured. |
|
How is the SEID built? |
A Windows SID. |
3.4.5. LDAP
The LDAP security configuration mechanism allows interoperability with an LDAP environment.
It can be used to authenticate users against any kind of LDAP server. A Sun One or iPlanet LDAP Server can be used, for instance, to authenticate Plastic SCM users.
It can also be needed on mixed Windows / Unix Active Directory environments. The server can be configured to work with Active Directory Integrated Security, and Unix clients can authenticate against Active Directory using LDAP.
|
How does the server obtain the user list? |
From the LDAP Server using a given user and password. |
|
How is the SEID built? |
The ID used by the concrete LDAP mechanism. |
3.4.6. User/Password
The user/password authentication system introduces an easier way to configure Plastic in a user – group based authentication in certain environments. When LDAP, Active Directory and local server authentication mode are not available options, the system administrator can select user/password authentication.
When using UP (short for user/password authentication) the Plastic security system works exactly as it would do with LDAP, Active Directory or any other mode, the only difference is how the users, groups, their relationships and the passwords are stored.
When working in UP mode the administrator will define users, groups and their relationships using a specific Plastic configuration tool, then the client will just have to specify the previously configured user and password to log in the Plastic server.
UP working mode is appropriate for mixed Linux/Windows environments where LDAP or Active Directory integration is not an option, or to manage access to the Plastic server on heterogeneous environments where the built-in operating system’s authentication mechanism doesn’t match.
To configure the login and password the user must run the Plastic configuration wizard as shown on the following figure.
Figure 15: User and password configuration screen
On Plastic GUI client start up if the user and password are not correctly set, the login screen will pop up.
Figure 16. Login dialog
The main difference between UP and the other authentication systems is that instead of relying on an external user and group provider, the UP authentication mode stores all its data into two files: users.conf and groups.conf.
- users.conf: stores information about all the users and their encrypted passwords.
- groups.conf: stores all the available groups and the users they contain.
Figure 17. Involved configuration files in UP mode
Configuring user/password authentication mode
In order to configure the UP mode you’ll use the following tools:
- The server’s configuration tools (configureserver or clconfigureserver) to set the authentication mode the server has to use.
- The client’s configuration tools (plastic --configure or the configuration wizard) to specify the authentication mode to communicate with the server.
- umtoolgui or umtool to configure the users, groups, and their relationships both graphically and from the command line.
Selecting the UP authentication mode
To select the UP authentication mode both the clients and the server must be configured accordingly.
Plastic users can run both the server’s configuration wizard (configureserver executable) and the client’s configuration (plastic --configure) to set the UP authentication mode as described on the figure below.
umtoolgui
umtoolgui is the GUI tool to configure the users, groups and their relationships and passwords. The tool is located on the server’s directory.
The following figure describes all the umtoolgui functionalities. It is a very simple and intuitive tool which solely purpose is to help users configure the users.conf and groups.conf files.
The tool is able to create users and groups, assign users to a specific group, change an user’s password, rename users and groups and delete them.
Figure 18. umtoolgui functionality umtool
umtool is the command line tool used to configure the users, groups and their relationships and passwords from the operating system’s console.
umtool implements several commands detailed on the following table.
|
Command name |
Short name |
Description |
Syntax |
|
addgrouptogroup |
agtg |
Include a new group into a group |
umtool addgrouptogroup <grouptoadd> <groupname> |
|
addusertogroup |
autg |
Include a new user into a group |
umtool addusertogroup <username> <groupname> |
|
changeuserpassword |
cup |
Change a user’s password |
umtool changeuserpassword <username> <oldpassword> <newpassword> |
|
creategroup |
cg |
Create a new Plastic SCM group |
umtool creategroup <groupname> |
|
createuser |
cu |
Create a new Plastic SCM user |
umtool createuser <username> <password> |
|
deletegroup |
dg |
Delete a existing Plastic SCM group |
umtool deletegroup <groupname> |
|
deletegroupfromgroup |
dgfg |
Delete a group from a group |
umtool deletegroupfromgroup <grouptodelete> <groupname> |
|
deleteuser |
du |
Delete a existing Plastic SCM user |
umtool deleteuser <username> |
|
deleteuserfromgroup |
dufg |
Delete a user from a group |
umtool deleteuserfromgroups <username> <groupname> |
|
help |
hlp |
Show a command’s help |
umtool help <commandname> |
|
listgroupmembers |
lgm |
Show a list with members of a group |
umtool lgm <groupname> |
|
listgroups |
lg |
Show a list with current Plastic SCM groups |
umtool lg |
|
listusers |
lu |
Show a list with current Plastic SCM users |
umtool listusers |
|
renamegroup |
rg |
Rename a existing Plastic SCM group |
umtool renamegroup <oldgroupname> <newgroupname> |
|
renameuser |
ru |
Rename a existing Plastic SCM user |
umtool renameuser <oldusername> <newusername> |
users.conf file format
The users.conf file contains the definition of the users known to the system in UP authentication mode. The format of the users.conf file is very simple: it contains a list of the available users followed by their passwords as shown on the figure below.
Figure 19. users.conf file format
groups.conf file format
The groups.conf file contains all the groups known to the Plastic system in UP mode. The file is a list of the groups, each one followed by the names of the users or groups it contains. Check the following figure for details.
Figure 20. groups.conf file format
Setting server’s UP working mode modifying server.conf
After the server’s working mode is set, it will be stored on the configuration file named server.conf.
The server.conf file can be manually modified to choose a different authentication mode. To set the UP working mode use the workingmode value specified in the figure below.
Figure 21. server.conf contains WorkingMode
UP mode common questions
|
How does the Server build the list of users?
|
It retrieves the list of users´ names from the users.conf and the groups.conf files on the server folder.
|
|
What does the authentication contain? |
It contains the username and the encoded password. |
Table 3. UP common questions
This is the traditional authentication method; it allows Plastic SCM users to define their own users and groups on the Plastic server. This way Plastic works with an autonomous security mechanism, which could be the best option for many organizations which don't rely on systems like LDAP or Active Directory.
The server keeps a list of the users and each user defines his password. It also keeps groups as well as the relation between users and groups. Each client sets a user and a password in order to have access to the server, the user must exist on the server and the password must be the same one.
The list of users and groups is defined by two configuration files located on the server folder.
There are two tools used to manage users and groups, these tools can be found on the server’s installation directory:
umtool (command line tool)
umtoolgui (Graphic User Interface tool)
Plastic SCM server starts automatically when you start your computer, and after installation process is finished, but it can be stopped, started, or restarted manually.
3.5.1. Windows Systems
In order to manage Plastic SCM start, stop or restart from Windows Systems, you can open the Windows Service Manager. Open Control Panel, Administrative Tools, and Services. There you will find Plastic SCM service in the list:
Figure 22: Managing Plastic SCM server service
3.5.2. Linux Systems
In order to manage Plastic SCM start, stop or restart from Linux Systems, you can use plasticsd script. This script is located in the server installation directory (/opt/PlasticSCM/server by default). On RedHat based systems you can use the system call service plasticsd <options>. This script has the following options:
./plasticsd {start | stop | restart}
Once the Plastic SCM server is started, a default repository will be created, to ease the initial system usage.
You can check whether the server is up and running looking at the repository list. Follow the next steps:
Open a command line window (cmd.exe)
Type: cm lrep servername:8084, that will list all the repositories on server servername:8084.
Each time a new client is installed on a developer machine, it will have to be configured with the following steps.
|
Client configuration welcome screen. |
Figure 23. Client configuration welcome screen |
|
Language selection. |
Figure 24. Client configuration language selection |
|
You have to choose an authentication mechanism on the client, which must be the same as the mechanism selected on the server. There is one exception: if you are integrating Unix with Active Directory, the Unix system should use LDAP. |
Figure 25. Client authentication selection |
|
Choose the workspace server. You have to type the name of the server where you installed Plastic SCM, followed by the port you configured. If you didn’t change the server’s port during configuration, it will be port 8084. |
Figure 26. Workspace server selection |
Table 4. Client configuration steps
3.6.1. Merge and Differences Tools configuration
The configuration of the merge and differences tools is defined in the client.conf file. It must be configured in order to specify, through a set of rules, which tool has to be used and which parameter will be used with that tool, in order to do a merge or calculate the differences between different revisions of an item. A rule contains information regarding the type of file (binary or text) on which it must be applied, and either one or more extensions of that type of file will be specified as valid for that rule.
The default rules for the merge tool are the following ones:
- FileType: Indicates the types of files the rule applies to, they can be TextFile, for files identified as text by Plastic SCM or BinaryFile for files identified as binary by Plastic SCM.
- FileExtensions: Indicates the extensions of the types of files on which the rule is applied, if we have more than one extension for the same rule they would be separated by “;". If the rule is used for every extension "*" would be used.
- Tools: Different merge tools to be used with a specific file, if there is more than one they are executed in order until one of them gives a result; only the first one is used in the case of the differences. These tools must have every manatory parameter using the variables given, which are replaced by the system value during execution. If we want the system to use a specific value for a rule instead of a variable, that value would be set. The given variables are the following ones:
- @basefile: path containing the merge common ancestor.
- @basesymbolic: name shown on the tool to refer to the base file, it is usually the spec revision or the disc file if loaded.
- @basehash: common ancestor content hash.
- @sourcefile: path containing the merge source file.
- @sourcesymbolic: name shown on the tool to refer to the merge source file, it is usually the spec revision or the disc file if loaded.
- @sourcehash: merge source content hash.
- @destinationfile: path containing the merge destination file, the location of the element in the workspace.
- @destinationhash: merge destination content hash.
- @output: file containing the merge result.
- @filetype: type of file used for the syntax hightlight
- @comparationmethod: comparison method used.
- @fileencoding: file encoding.
- @mergetype: type of merge used.
It must be highlighted that rules are executed in order, so the less restrictive ones must be the last ones to be executed on this type of files.
Example using an additional rule for a single type of file considered as binary (.scs) if we want it to be considered as text and given fixed parameters: type of merge to be automatic only if one of the contributors has submitted changes and file codification as unicode:
<MergeTools>
<MergeToolData>
<FileType>enTextFile</FileType>
<FileExtensions>*</FileExtensions>
<Tools>
<string>mergetool
-b="@basefile" -bn="@basesymbolic"
-bh="@basehash" -s="@sourcefile"
-sn="@sourcesymbolic" -sh="@sourcehash" -d="@destinationfile"
-dh="@destinationhash" -a -r="@output"
-t="@filetype" -i="@comparationmethod" -e="@fileencoding"
-m="@mergetype"</string>
</Tools>
</MergeToolData>
<MergeToolData>
<FileType>enBinaryFile</FileType>
<FileExtensions>.scs</FileExtensions>
<Tools>
<string>"bmergetool.exe" -b="@basefile"
-bn="@basesymbolic" -bh="@basehash"
-s="@sourcefile" -sn="@sourcesymbolic"
-sh="@sourcehash" -d="@destinationfile"
-dh="@destinationhash" -a -r="@output"
-t="@filetype" -i="@comparationmethod"
-e="unicode" -m="onlyone"</string>
</Tools>
</MergeToolData>
<MergeToolData>
<FileType>enBinaryFile</FileType>
<FileExtensions>*</FileExtensions>
<Tools>
<string>binmergetool
-b="@basefile" -bn="@basesymbolic"
-bh="@basehash" -s="@sourcefile"
-sn="@sourcesymbolic" -sh="@sourcehash" -d="@destinationfile"
-dh="@destinationhash" -a -r="@output"
-m="@mergetype"</string>
</Tools>
</MergeToolData>
</MergeTools>
In the case of the differences tools, rules are build similarly but there are less given variables. In order to add a rule to calculate differences on a binary file (.scs) as a text file with unicode format, we would write the following:
<DiffTools>
<DiffToolData>
<FileType>enTextFile</FileType>
<FileExtensions>*</FileExtensions>
<Tools>
<string>mergetool
-s="@sourcefile" -sn="@sourcesymbolic"
-d="@destinationfile" -dn="@destinationsymbolic" -a
-t="@filetype" -i="@comparationmethod"
-e="@fileencoding"</string>
</Tools>
</DiffToolData>
<DiffToolData>
<FileType>enBinaryFile</FileType>
<FileExtensions>.scs</FileExtensions>
<Tools>
<string>"bmergetool.exe" -s="@sourcefile"
-sn="@sourcesymbolic" -d="@destinationfile"
-dn="@destinationsymbolic" -a -t="@filetype" -i="@comparationmethod"
-e="unicode" </string>
</Tools>
</DiffToolData>
<DiffToolData>
<FileType>enBinaryFile</FileType>
<FileExtensions>*</FileExtensions>
<Tools>
<string>binmergetool
-s="@sourcefile" -sn="@sourcesymbolic"
-d="@destinationfile" -dn="@destinationsymbolic" -a
-t="@filetype" -i="@comparationmethod"
-e="@fileencoding"</string>
</Tools>
</DiffToolData>
</DiffTools>
4.
Creating and managing
repositories
Repositories are the center pieces in the Plastic SCM system. They store all the information of all the objects inside the system.
An empty repository named default is created during server start up, if no other repository exists yet.
More repositories can be created using the following steps:
Type the following command:
cm mkrep PlasticServer:8084 NewRepository
PlasticServer:8084 is the server machine name plus port number and NewRepository is the name of the new repository
It is also possible to create a repository using the GUI tool. The Figure 27 shows the repository creation dialog on the GUI.
Figure 27. Creating a new repository
Listing available repositories can be done in two different ways: from the command line and using the GUI client.
Let’s first have a look at how to list repositories from the command line:
cm lrep PlasticServer:8084
Will show the following output (three repositories created):
2
codice 192.168.1.208:8084
4 cmmi 192.168.1.208:8084
6 XBRL 192.168.1.208:8084
Figure 28 shows the repositories view on the GUI tool, accessible from the View menu.
Figure 28. Repositories view
Repositories that are no longer used can be disconnected from the server and archived on offline storage like DVD or tapes, leaving free space for active repositories. These repositories can be later reconnected if they need to be used, following the procedures described here.
In order to archive a repository, the removerepository command is used, providing a repository specification. Before removing a repository, you should ensure that no workspace is using it. In any case, Plastic SCM will complain if this condition is detected, and will list the workspaces using the repository when trying to remove. First, list all repositories:
C:\scm3>cm
lregrep
default 1 default localhost:8084
myproject 3 myproject localhost:8084
nasaproject 5 nasa localhost:8084
Get the number in the second column for your repository. In the sample, we want to archive repository 3 (myproject). This number will be used later to identify the file to backup. Next is removing the rep:
cm removerepository myproject@localhost:8084
This command has two internal effects, important to note for later reconnection. First, it removes the repository from the list of registered repositories available to be used in workspaces. Second, it removes the repository from the list of available repositories.
As noted before, while performing this operation, you may get an error indicating that some workspaces are using this repository:
C:\scm3>cm
removerepository myproject@localhost:8084
Registered repository can't be removed because the following workspaces have
revisions pointing to it: myworkspace
To correct this, ensure that the workspaces are removed or point to a different repository.
Now, go to the database storage location (by default, the server installation folder). Repository files follow the naming
rep_xx.plastic.fdb
The file for myproject repository, in the sample, will be
rep_3.plastic.fdb
This is the only file you need to archive on DVD or the media of your choice.
To reconnect an archived repository, first get a list of current repositories (this might be different from the list of reps found when it was archived)
C:\scm3>cm listregisteredrepositories
default
1 default localhost:8084
excel 3 excel localhost:8084
word 4 word localhost:8084
pwpoint 5 pwpoint localhost:8084
access 6 access localhost:8084
outlook 7 outlook localhost:8084
In the sample, several repositories have appeared since we archived myproject, which had number 3. Choose a free repository number not used in the list (next one is 8, but you can choose any other). Rename your rep_3.plastic.fdb to rep_8.plastic.fdb:
move rep_3.plastic.fdb rep_8.plastic.fdb
And now for the reconnect: first add the repository to the list of available repositories:
cm addrepository rep_8 myproject localhost:8084
The first argument is the database name, without the .plastic.fdb extension.
The second argument is the name for the repository. This must be unique in the list of available repositories.
The last argument is the repository server where the repository will be connected.
Next step is to publish in the list of repositories available to workspaces:
cm registerrepository myproject@localhost:8084
It is now ready to be used by the clients. You might need to close and reopen graphical clients so that they can use the reconnected repository.
5. Creating and managing workspaces
Workspaces define the way users have to work on the items stored on the repositories. To be able to check out files and directories and work on them, a workspace is needed.
A workspace actually maps a given repository status onto a certain location on the user’s drive.
To start working with Plastic SCM, a user needs to have a workspace. The workspace is both the place on the local disk to store the downloaded files and directories from the server, and an associated configuration and versioning information.
A workspace can be created from the command line typing:
cm mkwk myworkspace c:\workspace
myworkspace is the name of the newly created workspace, and c:\workspace its location.
It is also possible to create a repository using the GUI tool. Figure 29 shows the repository creation dialog on the GUI.
Figure 29: Creating a new repository
The GUI tool can list all the available workspaces from the workspaces View.
From the view shown on Figure 30 new workspaces can also be created.
Figure 30. Workspaces view
Workspace listing can also be achieved from the command line tool typing:
cm lwk
Displaying the following output:
Wk_code_metrics@BEARDTONGUE Pablo d:\data\code\codemetrics
Pablo_wk@BEARDTONGHE......Pablo......d:\data\code\wkspaces
Workspaces are controlled by the server and contain information to know the exact revisions loaded on the client machines. This way no extra information is stored on local directories, just data. This is very helpful to avoid directory pollution.
Administrator or SCM manager can decide that certain workspaces shouldn’t be used anymore. In that sense he will remove them, meaning the server will not know about them anymore.
When a workspace is removed, its data is deleted from the server, but nothing is removed on the user’s local disk.
Workspace removal can be achieved from the workspaces View on the GUI tool, or it can be performed from the command line typing:
cm rmwk c:\workspace
A workspace can also be moved, meaning its current configuration can be downloaded into any other location. This can be useful dealing with users moving from one workstation to another.
Workspace moving is a very specific operation that can only be currently triggered from the command line.
cm chgworkspace testwk c:\new_path
6. Independent workspace and repository servers
A Plastic SCM server manages two important concepts: repositories and workspaces. A repository is a database where all the versioned objects are stored. A workspace is an area on the developer’s disk where a copy of a project stored in a repository is downloaded so that the developer can work with it locally: edit the code, compile it, make changes to documents and so on.
All the information about the files and directories stored in the developer’s local copy, the workspace, and the revisions they’re associated to are actually stored on the server, so that the local disk is not polluted with non essential information.
Figure 31 shows three developers’ workspaces and how their data is mapped into server’s workspace database. The server in the sample is managing three workspaces and a collection of two repositories.
In the default configuration a Plastic Server manages both repositories and workspaces, but the system is flexible enough to allow different layouts. Different repository and workspace servers can be configured to cooperate enhancing overall system performance, reducing network usage, distributing storage and balancing CPU load.
Figure 31: Developer´s workspaces and how they relate to server´s storage
When Plastic SCM server is first installed a combined repository and workspace server is set up. Users have to configure their client machines to connect to a plastic server. The server the user is introducing is actually a workspace server. Each client needs a workspace server to work, which in turn knows a list of repositories and the repository servers where they’re stored. By default only one repository server is used and it is executed as a single process together with the workspace server.
There are three server running modes also known as server types. Depending on how a server is configured it can run as a standalone repository server, a standalone workspace server or a combined workspace and repository server (default).
The three server types are defined as:
- ServerTypeAll: this is the default configuration mode. The server process will run both a workspace and repository server. It accepts both workspace and repository server requests.
- ServerTypeWorkspace: the server will behave as a standalone workspace server. It will reject any repository requests.
- ServerTypeRepository: the server behaves as a repository server, rejecting all workspace server requests.
As stated above, Plastic SCM server infrastructure gives the system administrator’s lots of flexibility. The out of the box configuration deploys a combined repository and workspace server on a single process on a single machine, but other possibilities are available.
Figure 32 depicts a possible deployment scenario in which the workspace and repository servers run on separate machines. The workspace server must know which ones are the available repositories, and to do so it uses the registered repositories list, which is just a collection of the known repositories, the repository servers where they reside and their aliases in order to be easily manipulated.
A Plastic SCM client application (command line client, graphical user interface client, IDE integrations and so on) will always know which one is its workspace server. This is the required information needed to start working. The workspace server will tell clients which ones are the repositories they can work with. So network connections always happen in the same sequence: first the workspace server is contacted and then, if required, the client will directly connect to the repository server.
It is important to note that all the different servers and clients must have the same authentication mode defined (or a compatible one) in order to work together successfully.
There are several advantages introduced by a deployment layout like the one introduced in the sample:
- Better network performance can be achieved with a careful design of the Plastic SCM deployment schema.
- Increased performance due to load balancing several projects into different repository servers.
Figure 32. Separated workspace and respository server deployment
The deployment schemas introduced so far have shown the possibility of introducing separate workspace and repository servers, splitting the load and achieving better performance results under load conditions.
This topic will push things even further introducing the possibility of setting up multiple workspace servers.
Figure 33 illustrates a network configuration in which a workspace server is installed to attend a certain number of client machines. The workspace servers, in turn, connect to a central repository server.
The workspace server manages all the information about the local copies stored by the developers’ machines, so they can end up handling a big amount of processor load. Introducing more than one server will help reducing their load and increasing overall system performance. Of course it will greatly depend on the amount of load and the number of users.
Figure 33. Multiple workspace servers working with a single repository server
Another deployment strategy based on multiple workspace servers is installing a workspace server on each developer’s machine. This way each workspace server will normally attend only one client and it will contribute reducing both network traffic and server’s load.
Figure 34 describes the scenario introduced above.
The specific workspace server strategy to be used will greatly vary depending on each development group’s needs, available hardware and network topology. What is interesting to note is that Plastic provides enough flexibility to be adapted to any circumstances, from the easiest set up using a single server to the most expanded workspace server schema.
Figure 34. One workspace server installed on each developer's machine
The repository server handles the versioned data managed by Plastic SCM. Information about the branches, revisions, items, attributes, links, permissions and file and directory data is totally managed by the repository server.
The Plastic SCM design presents repositories as semi-transparent entities to the version control clients: each client application knows how to connect to the workspace server and from there this server will tell them how to connect to a specific repository server.
In the default set up both type of servers are deployed together so there is a one to one relationship between the two server entities. This can be easily changed to obtain better performance or network usage.
The users normally refer to the repository they’re working on by an alias. If you take a look at a typical Plastic SCM workspace selector you’ll see something like the selector 1 at Figure 35. The selector is just referring to the repository plasticcode but the user doesn’t have to know where this repository is stored. In the default server deployment the repository will be stored on the only installed server, but when a multi-repository set up is available, the workspace server will define which the list of registered repositories is.
In the figure there’s a sample execution of the lregrep command which shows the list of registered repositories on a workspace server (by default it connects to the configured workspace server). In the sample there is a list of several registered repositories. The list shows the alias, the repository id in the corresponding repository server, the name and the server where it is located. Some of the repositories have been registered with an alias which is different to the name. This is the value used in the selectors to choose the repository to work with.
Figure 35. Sample selectors and their mappings to the registered repositories
For instance the repository plasticcode used in the selector 1 shown in the figure maps to the repository codice at the repository server juno at port 9090.
The second sample selector in the figure shows a multi-repository selection rules. Content from up to six repositories will be downloaded to the workspace according to the defined rules. There’s no need to actually specify where the repositories are located but just their aliases.
Figure 36 shows a sample multi-repository set up in which one single workspace server works with two different repository servers. The figure also shows the mappings between the known repositories and their real locations on the repository servers.
Clients don’t need to know where the repositories are actually located because this will receive this information at runtime from the workspace server.
Like multi-workspace server deployment, using multiple repository servers can help to increase overall network performance and system scalability.
Because the workspace server is the only one aware of the actual repository locations, server topology can be changed without altering client configurations, which greatly eases system administration.
Figure 36. Multi-repository set up
It is possible to combine having multiple workspace and repository servers to achieve a full parallelized Plastic network topology. Figure 37 shows a sample configuration schema in which one workspace server is set per group of developers, and then three repository servers attend all the combined load.
Figure 37. Multi server deployment schema
Another interesting feature is the ability to set up independent database servers. Plastic SCM workspace and repository servers store all their data in relational databases, so if maximum performance is required, the business layer can be separated from the database one as shown on Figure 38.
Figure 38. Separated database server
To specify which one is the server type to run the administrator must edit the server.conf xml configuration file. Take a look at Figure 39 for a detailed explanation.
Figure 39. Modifying server.conf to set up the server type
After modifying the configuration file the system administrator will have to restart the Plastic SCM server.
To configure a multi-server Plastic scenario the system administrator’s will need to modify the list of registered repositories on the installed workspace servers.
To do so the sysadmin will use the following commands: lregrep, regrep and unregrep.
6.9.1. Adding a registered repository
To add a registered repository to a workspace server the administrator will use the regrep command.
The syntax of the regrep command is as follows:
cm regrep repositoryspec [alias]
Samples:
cm regrep rep:myrep@repserver:MYSERVER:8084
cm regrep rep:myrep@repserver:MYSERVER:8084 myrepAlias
An optional alias can be specified, which will be used to define the different selectors.
6.9.2. Removing a registered repository
In order to remove a registered repository use the unregrep command.
cm unregrep repository_alias
Samples:
cm unregrep myrepAlias
6.9.3. Listing the registered repositories
To retrieve the list of registered repositories use the lregrep command.
cm lregrep
7. Repository data location
By default, Plastic SCM databases are stored on the server installation folder. However, this might not be the best place for them so this setting can be changed following the procedure described here:
· Stop Plastic SCM service.
· In the server installation folder (usually c:\program files\plasticscm\server on Windows platform), create a file called db.conf, with this content:
<DbConfig>
<ProviderName>firebird</ProviderName>
<DatabasePath>c:\myRepositoryStore</DatabasePath>
</DbConfig>
· Specify the new storage folder inside the DatabasePath tag of this file and save.
· Move any file with .fdb extension in the server install folder to the folder you specified so that your existing data is used in the new location.
· Start the plastic server.
8. Backup and restore
The backup and restore procedures are closely related to the database backend used in Plastic SCM. Default installation of the server uses an embedded Firebird database engine, and the following instructions are meant for that configuration. If you have configured a different database backend, please check the guide for that backend for specific backup instructions.
Plastic SCM requires the administrator to stop the running server in order to perform the backup. Taking this into account, backup is very simple, and can be easily automated with a shell script if needed:
· Stop Plastic server
· Copy *.fdb files in your repository data location (by default, server installation folder, or the path in the DatabasePath tag of the db.conf file if it has been configured)
· Start Plastic server again.
Note that, while it is safe to perform an online backup if no operation is being performed by clients, (not requiring to stop the server) currently there is no way to check this condition, so the recommended procedure is stopping the server.
Restore procedure is very similar to backup:
· Stop Plastic server
· Copy *.fdb files from the backup to the repository data location. To keep consistency, it is important to copy all files.
· Start Plastic server again.