This is a guide on how to run CTFd using the provided Vagrantfile.

1. Quick Start
2. Background and Dependencies
3. Workflows
4. Troubleshooting
5. Behind the Scenes

git clone https://github.com/CTFd/CTFd.git
vagrant up

Visit https://localhost:8000 where CTFd will be running.

See the Getting started page for more information. If you recieve an error when visiting the site please see the troubleshooting section.

Vagrant is a tool that "makes development environments easy" by simplifying and standardizing the creation and configuration of virtual machines. With Vagrant all the dependencies for CTFd will be automatically installed inside a virutal machine so you can develop on the platform without installing anything else on your system. For more information on how this project uses Vagrant please see the behind the scenes section.

In order to use Vagrant you need to install it and a virtualization platform such as VirtualBox.

• Installation instructions for Vagrant
• Installation instructions for VirtualBox

• source code (from your host) machine is synchronized into the VM in the /vagrant directory.
• CTFd Python dependencies are installed into a virtualenv managed by virtualenvwrapper named ctfd.
• Docker is installed so you can develop with containers.
• On boot the VM starts a tmux session named ctfd running CTFd with gunicorn as described here.
• Ports 4000 and 8000 are forwarded from the VM to the host machine.

vagrant ssh

vagrant ssh
cd /vagrant
docker-compose up

When switching between the gunicorn server or development server and the docker method, make sure to clear your browser state, otherwise it may result in database errors and 500 error codes.

vagrant ssh
cd /vagrant
workon ctfd
nosetests

• stop: vagrant halt
• status: vagrant status
• remove: vagrant destroy

vagrant ssh
tmux attach ctfd

The site fails to load after vagrant up, or the tmux session does not exist:

1. Try reloading the vm with vagrant reload. This will reboot the vm a attempt to restart the gunicorn server.
2. Try manually starting the CTFd service.

   cd /vagrant
   workon ctfd
   python serve.py
   

There are errors during vagrant up (this may happen due to an intermittent network error that results in a failure to download and install a dependency).

1. Try rebooting the VM and re-running the installation steps.
   • vagrant reload --provision
2. Try recreating the VM.

   vagrant up
   

This section is intended to provide a better idea of what happens when you run vagrant up. All of the settings described here are configured in the Vagrantfile or its related scripts.

First Vagrant goes out and fetches a "base box". This is a minimal VM image which it will then customize. This Vagrantfile is based off of a Ubuntu 16.04 (Xenial Xerus) machine. This step may take some time because it has to download an entire VM, but fortunately this is a one time step.

Next, the "base box" will automatically be booted in VirtualBox, or whatever your virtualization platform is.

On first boot, and whenever vagrant up is called with the --provision flag, the machine will the run a number of provisioning steps. These are to install the dependencies necessary for running the CTFd platform. For the most part these are all contained in ./prepare.sh. The only custom steps this Vagrantfile takes is to install the Python dependencies into a virutalenv. This step may also take some time but only the first time.

Finally, the Vagrantfile will launch the CTFd service. It tries to do this in a tmux session as described above. The VM then forwards those ports (4000,8000) to your local machine.

In the end you have a completely contained and reproducible environment to develop on CTFd. You can easily stop, start, or recreate it all without any major modifications to your machine.