How-to Perforce with Friends

Want to develop a game with friends or a community? Have a spare computer you aren’t using, or have a current home lab server with some extra resources?

Most guides show you how to host Perforce on your main PC, but this reduces the available resources of your workstation. Perforce is a excellent tool for version control. It supports large filesize and it the current choice for source control of a lot of studios.

In this guide we will install and configure a Helix Server, manage the depot, users, and groups using the P4Admin client, and setup a simple organized yet effective content architecture. This architecture setup will allow us to seperate the source art from the development depot, so our depots aren’t cluttered with unecessary content. The Helix Server will be hosted on a Ubuntu server, but the setup can be applied to any OS.

The Plan

So here’s what we’re going to do.

Add the Perforce repository to your APT configuration.
Install the Helix Core packages.
Setup and mount separate drives for performance. You can skip this step, though. a. I recommended having separate drives for each of the following files: db.*, journal, and archive files.
Configure the Helix Server.
Tuning the server for performance.
Install the P4V client on your workstation.
Connect to your Helix Server.
Setup Depots, Streams, Permissions, Users, and Groups.
Setup tailscale for a simple gateway for the Team to connect.
Setup Perforce in Unreal.
Setup Perforce in Unity.

Hardware Recommendations

Perforce doesn’t require high-end hardware, so here’s a quick run down of what’s recommended. Link to the documentation where it mentions minimal requirements for running a Helix Core server.

CPU: at least 2.6GHz and 6 cores.
- Prioritize high-frequency CPUs.
Memory: 8GB
Boot disk: 40GB
Data Storage: SSD
- 3x SSDs, if you want as much performance from the drives. With each drive hosting the following files separately.
  - Database files
  - Journal files
  - Depot files

My Hardware Setup

I’ll add my hardware setup for reference, and hopefully, it can be helpful. I also use this server to host a number of applications using Docker. It is a bit overkill just as a Helix Server, but I left room for myself to add more applications. The S500+ has a small footprint, is power efficient, and powerful.

Server: Morefine S500+ 5900HX Mini PC

CPU: Ryzen 9 5900HX
RAM: 16GB DDR4
Boot Disk: 500 GB
Storage:
- 2x 500GB NVMe SSDs
- 2x 500GB SSDs
- 1x 1TB SSD

Installing Helix Core Server in Ubuntu

Adding the packages to APT

Parts of this section is pulled straight from the documentation.

Add the Perforce packaging key to your APT keyring.

wget -qO - https://package.perforce.com/perforce.pubkey | sudo apt-key add -

Add the Perforce repository to your APT configuration. Where {distro} is your current distribution codename. You can find out by running the following command:

lsb_release -a

Since I’m using Ubuntu 20.04 on my server, {distro} was set to focal.

echo deb http://package.perforce.com/apt/ubuntu {distro} release | sudo tee /etc/apt/sources.list.d/perforce.list

sudo apt-get update

Install the required helix core packages. The following command will install helix-p4d along with helix-p4dctl and helix-cli.

sudo apt-get install helix-p4d

Setting up the Drives

Skip this step if you don’t have the extra hard drives.

I recommend creating the directories and mounting the drives first before running the configuration wizard. After reinstalling the software four times, I realized it is best method, or you’ll break your server configuration and have to start over.

With that in mind, figure out where you’ll want the configuration wizard to install the files for your Helix Server. The default locations are as follows:

Root directory: /opt/peforce/servers/*SERVICE NAME*
db.*files: /opt/peforce/servers/*SERVICE NAME*/root/
journal files: /opt/peforce/servers/*SERVICE NAME*/journals/
depot / archive files: /opt/peforce/servers/*SERVICE NAME*/archives/

The simplest way to set up the drives is to mount them in those locations.

Running the Helix Server Configuration wizard

It is a relatively simple process. You have seven options to answer, but you can accept all the defaults. I will explain each one as simply and best as I can.

Imgur

[value] is the default value.

Service-name [master]: You can run multiple instances of the helix server. The service name will be the identifier for each instance.
P4PORT [ssl:1666]: The port number to access the helix server.
P4ROOT [/opt/perforce/server/master]: The root directory for the helix server.
Super-user [super]: The server admin username.
Super-user password []: The password for the admin account.
Unicode mode [No]: This is the supported character set. Unicode mode is useful for people of differing languages.
Case-sensitive [Yes]: Whether the server is case-sensitive. Windows P4V clients don’t support case sensitivity.

Once you’ve completed the configuration wizard. The Helix Server should now be running and you can double-check by running the command:

sudo -u perforce p4dctl status {service-name}

Tuning the server for performance

This next section will improve the peformance of the Helix Server. Do a quick Google search on the CPU for your server to find out how many threads it contains so that you can tune the following options accordingly. These options will allow the transfer of files in parallel during the submit and sync processes.

p4 configure set net.parallel.max=4 # Should not be larger than the number of CPU threads.
# The following 3 commands should be less than or equal to net.parallel.max.
p4 configure set net.parallel.submit.threads=4 
p4 configure set net.parallel.threads=4 
p4 configure set net.parallel.shelve.threads=4

Installing P4V on your workstation

During the installation, I recommend installing the P4Admin client when the option presents itself. It has a nice GUI to manage depots, users, and groups and is how we manage these areas later.

P4V client installation

Connecting to your Perforce server

Launch the P4V client once the installation is complete. In the following window, we can ignore the Workspace: field for now. Input your server IP in the Server: field as ssl:your-server-ip:1666. Then log in using the super-user and password created during the Helix Server configuration step. Congratulations! You’ve set up and installed a Helix Server and connected to it.

P4V client

Creating Users and Groups

Once you’ve logged in using the P4V client, head to the Tools dropdown menu and select “Administration”. This will launch the P4Admin client.

Tools dropdown menu

From the P4Admin client, we can manage the depot, permissions, users, and groups. We’ll setup a stream depot for development and another for the source art. Seperating the main development files from the source files allows for a more effective and organized approach. Source art are large files that most artists don’t need to touch, so it’s best to be kept in a separate depot.

Create a User

Let’s head to the Users & Groups tab to create our first user. The free license of Helix Server does not allow users to create their accounts, so as the super user, we will have to create the user and password for each team member. I recommend using a passprase generator to create the passwords for each user.

Right-click on the white space under the super user.
Select New User…
Fill in the User, Password, Full name, and Email fields.
Select OK.

Create a Group

Now we can create a group and assign it to the first user.

Right-click on the white space in the Group column.
Select New Group…
Give the Group a name.
Press the Browse… button under the Users section.
Select the User we created earlier.
Select OK.

We’ve now created a user and a group. Permissions are unnecessary to set at the moment, but browse to the Permissions tab. Here we can set the permissions to any group or user for a specific folder/file.

Creating the depot and streams for your project

Head over to the Depots tab and setup a depot. There are seven types of depots we can create, but we will focus mainly on a stream depot. A stream depot is a container for a set of streams, a type of branch, and is writable. We will create two streams from in this depot, the main development stream and an art source stream.

Right-click on depot.
Select New Depot…
Enter a name for the new depot. Keep it short. Use a codename for your project if you have one.
Select Ok.
In the Depot type: section, select stream.
Set the Stream Depth to 2.
Select OK.

Nice! We’ve now set up our first depot. We set the Stream Depth to 2, which determines the path structure of where the depot will store the streams. In our case, the streams will be as follows, //depotName/project/main and //depotName/artsource/main.

Setup Streams

We can close the P4Admin client and head back to the P4V client. From the P4V client will create the main development stream and source art stream. We can use either the super user or any other user to make the streams.

In the View dropdown menu, Select Streams.
Right-click on the whitespace in the Streams tab.
Select New Stream…
Make sure to stay in the Basic Settings tab.
Set the Stream name as project/main.
Set the Stream type as mainline.
Set the Depot as the stream depot we created previously, if not already set.
Set a description for the stream. ex. Main development stream.
Uncheck the boxes for “Create a workspace to use this stream” and “Populate the mainline stream after it is created”.
Select OK.
Do the same setup for the source art stream.

Good work! We’re nearly there, and now we need to set up a workspace to allow us to work in these newly created streams.

Setup Workspaces

Now we have everything to allow version control in our project. I would recommend documenting the steps for setting up a workspace so that you can forward the workflow to your Team. Workspaces allow us to switch between working on different streams and depots. One thing to consider is that workspace names must be unique, and users cannot share workspace names. I recommend setting up a workspace naming convention for your Team. ex. username_projectNameDev or username_projectNameArtSource

In the same Streams tab, Right-click on a stream.
Select New Workspace…
Set a name for Workspace name.
Select OK.
Follow the same steps for the other stream.

Using Tailscale for friends and Team members

Tailscale is an easy-to-use VPN. It’s not a VPN about concealing your data instead, it creates a secure connection between the server and your Team or friends. It’s as simple as installing the tailscale app, connecting to the VPN, and that’s it.

Create a tailscale account at https://tailscale.com/
Install Tailscale on the server.
This section is not necessary, but it gives your server an easily readable name.
- Create a Cloudflare account.
- Get a domain if you don’t have one already.
- Create an A record with the Tailscale IP of your server.
  - This is reasonably secure as no one can connect to your server unless the server is shared via tailscale.
Share your server with your Team with an invite link.
Allow them to connect to Perforce using the tailscale IP of the server.

Installing tailscale on the server

curl -fsSL https://tailscale.com/install.sh | sh

Update the APT packages and install tailscale.

sudo apt-get update
sudo apt-get install tailscale

Start tailscale on the server.

sudo tailscale up

You can find the tailscale ip by running the following command or from the account dashboard on tailscale.

tailscale ip -4

Next, invite your Team one at a time by going to the Machines dashboard on the tailscale website, selecting Sharing settings, and generating a link for each member.

tailscale invite

Anyone that accepts the invite link should now be able to connect to the Helix Server.

If anyone has trouble connecting to the server via tailscale, I recommend closing the application and retrying. It happened a couple of times for me, and it appears to be a bug on the client’s end.

Enabling Perforce in Unreal

Launch Unreal Engine 5 or Unreal Engine 4.
In the Edit dropdown menu at the top, Select Plugins.
Search for Perforce in the search bar.
Enable the Perforce plugin.

Unreal Engine 4

In the toolbar, Select Source Control.
Select Connect to Source Control.
In the Provider dropdown menu, Select Perforce.
Enter the login info for the Helix Server.
Select Accept Settings.

Unreal Engine 5

On the bottom right-hand corner, Select Source Control Off.
Select Connect to Source Control…
Enter the login info.
Select Accept Settings.

That’s how simple it is to connect to Perforce using Unreal. It’s almost unreal, right? Haha, Ignore me.

Enabling Perforce in Unity

Launch Unity Hub
Launch the Unity Project.
In the Edit dropdown menu, Select Project Settings…
Select Version Control in the side menu.
In the Mode dropdown menu, Select Perforce.
Enter the login information.
Select Connect.

Nice! You’ve now connect Unity to Perforce! Unity can be very sensitive when it comes to how you handle moving and deleting files when using a Version Control tool. To keep this short, the rule of thumb is to move and delete files within Unity only. Unity relies on the meta files connected to each asset because it assigns a unique ID when a file is first imported into the project. Improper handling of these meta files can cause problems for the project later one, like submitting a changelist.

Conclusion

Perforce is a great source control tool. It allows for a Team to work on a project synchronously without affecting each other. So no one has to worry if they break the entire build in they local workspace. Inconjuction with Tailcale it can be a simple yet effective low budget setup for any Team.

I hope this helps you and your Team. Feel free to reach out if you run into any issues.

The Plan#

Hardware Recommendations#

My Hardware Setup#

Installing Helix Core Server in Ubuntu#

Adding the packages to APT#

Setting up the Drives#

Running the Helix Server Configuration wizard#

Tuning the server for performance#

Installing P4V on your workstation#

Connecting to your Perforce server#

Creating Users and Groups#

Create a User#

Create a Group#

Creating the depot and streams for your project#

Setup Streams#

Setup Workspaces#

Using Tailscale for friends and Team members#

Installing tailscale on the server#

Enabling Perforce in Unreal#

Unreal Engine 4#

Unreal Engine 5#

Enabling Perforce in Unity#

Conclusion#

References#