This bundle provides you with a fully functional Swarm deployment to get started with modding Swarm with a minimal amount of effort. One quick 'vagrant up' will create your own Swarm instance with a data laden Perforce server to start playing with.
To use this bundle you will need to download and install the following tools, both of which are free.
If you're not familiar with Vagrant it is a command line based virtual machine management tool that makes it easy to create and provision virtual machines, all driven by a simple text file. If you haven't used it before be warned; simple VM management is addictive.
VirtualBox is an open source hypervisor made by Oracle. It runs on many platforms and is the default hypervisor for Vagrant.
You do not need to know much of anything about Vagrant to use these tools. We'll explain the few commands you will likely need below.
Given that you are using a virtual machine you will need at least 512MB of RAM to run the Swarm environment. You will also need at least a gig of drive space to hold the VM image.
1) Grab the swarm_env.tgz file from http://swarm.public.perforce.com 2) Untar it into a directory of your choosing 3) Grab the latest build of Swarm from ftp.perforce.com and untar into the same directory 4) From a command prompt, cd to the directory that you originally created 5) Move the contents of swarm-<some version string> directory into the current directory. ex: mv swarm-2013.1-123456/* . 6) From the command prompt run 'vagrant up'.
The command 'vagrant up' tells Vagrant to look for the cleverly named 'Vagrantfile' and create the VM describe within. It will automatically download the required VM base image (Ubuntu 12.04 64-bit) and spin up a new VM. This base image download only occurs once. It will then execute the included Puppet scripts to deploy Swarm and p4d. Note you will need an internet connection during this process; it needs to fetch the p4 and p4d binaries from our site.
Once Vagrant returns you will have a fully functional Swarm and Perforce installation. Vagrant will forward Swarm to port 8080 on your machine and will forward Perforce to port 1666. From the command line you should be be able to run 'p4 -p 1666 info' and from the browser you should be able to go to "http://localhost:8080" and see your Swarm installation.
Note that right after the VM finishes creating the Swarm instance you may see the Swarm activity feed changing. This is normal and reflects that the new Swarm installtion is busily generating the activity feed from past history.
You will need very few commands to be successful with Vagrant for this project. Here are the commands you will need.
That's it! With those four commands you should be suitably dangerous to develop against Swarm successfully.
One important part of using Vagrant is taking advantage of the shared folders it creates. With this project we automatically link most of the files that are in the directory along with the Vagrantfile to appropriate places within the VM. For instance, the 'public' folder that came from the Swarm tarfile is linked in the VM to '/var/www/swarm/public'. By default all files and directories that are in the directory with the Vagrantfile are also shared to '/vagrant' on the guest VM.
These shared folders allow you to use your favorite editors on your computer with the files that are being used by the VM. Without SSHing in you can edit files live inside the VM. This is one of the biggest advantages of using Vagrant; it lets you code with your preferred tools while still having the controlled environment your app needs.
This also means that if at any point you need a clean test environment a quick 'vagrant destroy' and 'vagrant up' will give you a fresh installation with all of your code changes intact. 'vagrant destroy' only deletes the contents of the VM, not the contents of your host machine.
This Swarm project is setup to preserve the Perforce server even when 'vagrant destroy' is called. If you want an entirely clean environment make sure to delete the 'perforce' directory that gets created in the same directory as the Vagrantfile.
Here's a very generic example of how everything above comes together to allow you to modify Swarm.
1) Run the setup above. Once complete you have a fully functional Swarm installation. (warning: Vagrant will report that "stdin: is not a tty". Just ignore it. All is well.) 2) Begin adding your code. If you are working in PHP your code will go in the 'modules' directory. If you are working with 'CSS/js' you will add your code to 'public/custom'. 3) Test and code as needs be using your normal editor, browser, and Perforce client. 4) ... 5) Profit!
If you are working in PHP you will need to restart Apache to have it pick up your changes. This is not necessary when working with CSS/js; a simple page refresh will suffice. To do this:
1) Run 'vagrant ssh' from the directory you created to shell into the VM. 2) Run 'sudo service apache2 restart' to restart Apache and pick up your changes.
To properly version your work make sure to add all of the contents of the swarm_env.tgz(Vagrantfile and manifest directory) to source control as well as your code. That will make it easy to drop in different versions of Swarm as needs be.
There are a number of resources to help you get started with modifying Swarm.
The Swarm Help: http://localhost:8080/docs/extending/index.html Once you spin up your development enviornment as described above you can use the link above to access the applciation help on how to extend Swarm. It has links to the relavent frameworks and talks a bit about the existing RESTful interfaces.
Swarm Demo Extensions: http://swarm.public.perforce.com/projects/matt-attaway-swarm-demo-extensions This is a collection of simple modifications showing common ways of modifying Swarm. It's also where this development environment lives.
Bee Keys: http://swarm.public.perforce.com/files/guest/allan_yu/bee_keys This is a Swarm extension that shows how Javascript can be used to modify the behavior of Swarm. It adds navigational hotkeys that are quite useful.
If you need help or have comments or concerns swing by the Perforce forums at http://forums.perforce.com and post in the Swarm list. The Swarm and Community Development teams are very active there and will help you out in anyway possible.
Welcome ======= This bundle provides you with a fully functional Swarm deployment to get started with modding Swarm with a minimal amount of effort. One quick 'vagrant up' will create your own Swarm instance with a data laden Perforce server to start playing with. Requirements ------------ To use this bundle you will need to download and install the following tools, both of which are free. * VirtualBox (https://www.virtualbox.org/) * Vagrant (http://vagrantup.com) If you're not familiar with Vagrant it is a command line based virtual machine management tool that makes it easy to create and provision virtual machines, all driven by a simple text file. If you haven't used it before be warned; simple VM management is addictive. VirtualBox is an open source hypervisor made by Oracle. It runs on many platforms and is the default hypervisor for Vagrant. You do not need to know much of anything about Vagrant to use these tools. We'll explain the few commands you will likely need below. Given that you are using a virtual machine you will need at least 512MB of RAM to run the Swarm environment. You will also need at least a gig of drive space to hold the VM image. Usage ----- 1) Grab the swarm_env.tgz file from http://swarm.public.perforce.com 2) Untar it into a directory of your choosing 3) Grab the latest build of Swarm from ftp.perforce.com and untar into the same directory 4) From a command prompt, cd to the directory that you originally created 5) Move the contents of swarm-<some version string> directory into the current directory. ex: mv swarm-2013.1-123456/* . 6) From the command prompt run 'vagrant up'. The command 'vagrant up' tells Vagrant to look for the cleverly named 'Vagrantfile' and create the VM describe within. It will automatically download the required VM base image (Ubuntu 12.04 64-bit) and spin up a new VM. This base image download only occurs once. It will then execute the included Puppet scripts to deploy Swarm and p4d. Note you will need an internet connection during this process; it needs to fetch the p4 and p4d binaries from our site. Once Vagrant returns you will have a fully functional Swarm and Perforce installation. Vagrant will forward Swarm to port 8080 on your machine and will forward Perforce to port 1666. From the command line you should be be able to run 'p4 -p 1666 info' and from the browser you should be able to go to "http://localhost:8080" and see your Swarm installation. Note that right after the VM finishes creating the Swarm instance you may see the Swarm activity feed changing. This is normal and reflects that the new Swarm installtion is busily generating the activity feed from past history. Vagrant Basics -------------- You will need very few commands to be successful with Vagrant for this project. Here are the commands you will need. * vagrant up - creates and provisions a new virtual machine if one does not currently exist * vagrant destroy - halts and deletes the current virtual machine * vagrant ssh - ssh's you into the VM so you can work on the machine * vagrant halt - shuts down the virtual machine, but does not delete it That's it! With those four commands you should be suitably dangerous to develop against Swarm successfully. One important part of using Vagrant is taking advantage of the shared folders it creates. With this project we automatically link most of the files that are in the directory along with the Vagrantfile to appropriate places within the VM. For instance, the 'public' folder that came from the Swarm tarfile is linked in the VM to '/var/www/swarm/public'. By default all files and directories that are in the directory with the Vagrantfile are also shared to '/vagrant' on the guest VM. These shared folders allow you to use your favorite editors on your computer with the files that are being used by the VM. Without SSHing in you can edit files live inside the VM. This is one of the biggest advantages of using Vagrant; it lets you code with your preferred tools while still having the controlled environment your app needs. This also means that if at any point you need a clean test environment a quick 'vagrant destroy' and 'vagrant up' will give you a fresh installation with all of your code changes intact. 'vagrant destroy' only deletes the contents of the VM, not the contents of your host machine. ### Note ### This Swarm project is setup to preserve the Perforce server even when 'vagrant destroy' is called. If you want an entirely clean environment make sure to delete the 'perforce' directory that gets created in the same directory as the Vagrantfile. Workflow -------- Here's a very generic example of how everything above comes together to allow you to modify Swarm. 1) Run the setup above. Once complete you have a fully functional Swarm installation. (warning: Vagrant will report that "stdin: is not a tty". Just ignore it. All is well.) 2) Begin adding your code. If you are working in PHP your code will go in the 'modules' directory. If you are working with 'CSS/js' you will add your code to 'public/custom'. 3) Test and code as needs be using your normal editor, browser, and Perforce client. 4) ... 5) Profit! ### Note ### If you are working in PHP you will need to restart Apache to have it pick up your changes. This is not necessary when working with CSS/js; a simple page refresh will suffice. To do this: 1) Run 'vagrant ssh' from the directory you created to shell into the VM. 2) Run 'sudo service apache2 restart' to restart Apache and pick up your changes. Versioning Recommendations -------------------------- To properly version your work make sure to add all of the contents of the swarm_env.tgz(Vagrantfile and manifest directory) to source control as well as your code. That will make it easy to drop in different versions of Swarm as needs be. Educational Resources --------------------- There are a number of resources to help you get started with modifying Swarm. * The Swarm Help: http://localhost:8080/docs/extending/index.html Once you spin up your development enviornment as described above you can use the link above to access the applciation help on how to extend Swarm. It has links to the relavent frameworks and talks a bit about the existing RESTful interfaces. * Swarm Demo Extensions: http://swarm.public.perforce.com/projects/matt-attaway-swarm-demo-extensions This is a collection of simple modifications showing common ways of modifying Swarm. It's also where this development environment lives. * Bee Keys: http://swarm.public.perforce.com/files/guest/allan_yu/bee_keys This is a Swarm extension that shows how Javascript can be used to modify the behavior of Swarm. It adds navigational hotkeys that are quite useful. Help?!??! --------- If you need help or have comments or concerns swing by the Perforce forums at http://forums.perforce.com and post in the Swarm list. The Swarm and Community Development teams are very active there and will help you out in anyway possible.
| # | Change | User | Description | Committed | |
|---|---|---|---|---|---|
| #5 | 8415 | Matt Attaway | Fix up readme that I accidentally submitted | ||
| #4 | 8414 | Matt Attaway | Put Swarm in development mode to help with debugging | ||
| #3 | 8409 | Matt Attaway |
Harden the dev environment against 'vagrant halt' calls. This change adds a new Upstart script to start the Perforce server on startup and copies the P4PHP library to a static location so that Apache can properly load the module at boot time. Vagrant sets up the shared directories well after all of the services have been initialized which was causing Apache and Perforce grief. Also tweak a couple parts of the readme to clarify some of the odd Vagrant behavior. Many thanks to DJ for his help with testing the dev tools. |
||
| #2 | 8408 | Matt Attaway |
Fix issues with the dev environment * Add a mention to 'vagrant halt' so people know how to turn machines off * Store sampledepot files in a stable place so they don't get redownloaded * Adjust the triger manipulation script to be more precise Only remaining issue is figuring out a way to restart Apache. I may just copy p4-php to a different location to protect it from the shared directory creation. |
||
| #1 | 8401 | Matt Attaway | Add development environment for Swarm modding |