vagrant-wagtail-develop

A script to painlessly set up a Vagrant environment for development of Wagtail.

👋 Are you interested in a Docker-based environment? Check out docker-wagtail-develop.

Features

• An Ubuntu 22.04 (Jammy Jellyfish) base image
• Checkouts of Wagtail, bakerydemo, django-modelcluster and Willow ready to develop against
• Node.js / npm toolchain for front-end asset building
• Elasticsearch 5 installed (but disabled by default to make the VM less resource-heavy)
• Optional packages installed (PostgreSQL, Embedly, Sphinx...)
• Virtualenv for Python 3.9

Setup

Requirements: Vagrant, and a compatible version of VirtualBox.

Open a terminal and follow those instructions:

# 1. Decide where to put the project. We use "~/Development" in our examples.
cd ~/Development
# 2. Clone the vagrant-wagtail-develop repository in a new "wagtail-dev" folder.
git clone [email protected]:wagtail/vagrant-wagtail-develop.git wagtail-dev
# 3. Move inside the new folder.
cd wagtail-dev/
# 4. Run the setup script. This will set up all required dependencies for you.
./setup.sh

Note: On platforms that can't run shell scripts, run the commands from setup.sh manually instead.

It can take a while (typically 15-20 minutes) to fetch and build all dependencies - you could go for a coffee in the meantime :)

Here is the resulting folder structure:

.
├── libs          # Supporting libraries to develop Wagtail against.
├── vagrant       # Vagrant-related files.
├── wagtail       # Wagtail repository / codebase.
└── bakerydemo    # Wagtail Bakery project used for development.

Once setup is over,

# 5. ssh into your new Vagrant virtual machine.
vagrant ssh
# 6. Start up the bakerydemo development server.
./manage.py runserver 0.0.0.0:8000
# Success!

Alternatively, if you're using VSCode and have the "Remote - SSH" extension, you can connect VSCode to the vagrant VM directly. This allows for much deeper debugging. Once connected, open the /vagrant directory. A debug launch.json is included and ready to go.

Once wagtail is up and running,

• Visit your site at http://localhost:8000
• The admin interface is at http://localhost:8000/admin/ - log in with admin / changeme.

What you can do

Note: all of those commands are meant to be used inside the Vagrant virtual machine. To get there, go to your local Wagtail (cd ~/Development/wagtail-dev) set up and vagrant up then vagrant ssh.

Start the bakerydemo server:

./manage.py runserver 0.0.0.0:8000
# Then visit http://localhost:8000 in your browser.

Run the tests:

cd /vagrant/wagtail
# Python tests.
./runtests.py
# Node tests.
npm run test

Run the linting:

cd /vagrant/wagtail
# Python linting.
make lint
# JavaScript linting.
npm run lint

Build front-end assets:

cd /vagrant/wagtail
npm run build

Start front-end development tools and file watching:

cd /vagrant/wagtail
npm run start

Build the documentation:

cd /vagrant/wagtail/docs
make html

Start Elasticsearch:

sudo service elasticsearch start

To enable Elasticsearch on bakerydemo, add the following to bakerydemo/settings/local.py:

WAGTAILSEARCH_BACKENDS = {
    'default': {
        'BACKEND': 'wagtail.search.backends.elasticsearch5',
        'URLS': ['http://localhost:9200'],
        'INDEX': 'wagtail',
        'TIMEOUT': 5,
        'OPTIONS': {},
        'INDEX_SETTINGS': {},
    }
}

Getting ready to contribute

Here are other actions you will likely need to do to make your first contribution to the project.

Set up git remotes to Wagtail forks (run these lines outside of the Vagrant VM):

cd ~/Development/wagtail-dev/wagtail
# Change the default origin remote to point to your fork.
git remote set-url origin [email protected]:<USERNAME>/wagtail.git
# Add wagtail/wagtail as the "upstream" remote.
git remote add upstream [email protected]:wagtail/wagtail.git
# Add springload/wagtail as the "springload" remote.
git remote add springload [email protected]:springload/wagtail.git
# Add gasman/wagtail as the "gasman" remote.
git remote add gasman [email protected]:gasman/wagtail.git
# Pull latest changes from all remotes / forks.
git pull --all