Local Development: Setup

Overview

Workshop.codes runs on Ruby on Rails. Database is provided by PostgreSQL in production, with support for SQLite as a development/testing database. Search relies on Elasticsearch, which is provided by Bonsai in production. Some front-end code is created with Svelte, and all JavaScript code is packaged via Vite.

See the Testing frontpage for information on testing dependencies.

Pre-flight notes

• If you decide to use Windows Subsystem for Linux, please note that write-performance to the main Windows filesystem (e.g. /mnt/c) is MUCH SLOWER than writing to a folder contained with the WSL filesystem (e.g. /home/user/projects) (see this WSL issue for more details). Therefore, make sure you are setting up the project under a WSL-controlled directory, especially during cloning of the repository and subsequent steps.
• The most up-to-date instructions for setting up Rails can be found on this page at guides.rubyonrails.org.

Pre-clone setup

1. Ensure Ruby 3.0 is installed. You may want to use a Ruby version manager such as RVM to install Ruby if you intend to use multiple Ruby versions on your machine. Otherwise, installing directly via your preferred package manager or https://rubyinstaller.org/downloads/ should work as well.
2. Ensure NPM is installed. Instructions can be found at https://docs.npmjs.com/downloading-and-installing-node-js-and-npm.
3. Install either SQLite (recommended) or PostgreSQL. If you choose PostgreSQL, you will need to modify config/database.yml after cloning to utilize PostgreSQL in development and testing.
   • Note that SQLite may be installed as part of installing Rails itself in Post-clone setup.
4. (Optional) Install Elasticsearch (see https://www.elastic.co/downloads/elasticsearch for downloads and instructions for your system).
5. Install Bundler. Running gem install bundler after installing Ruby should accomplish this.
   • (Optional): Configure Bundler to ignore production gems via bundle config set without production
   • (Optional): Configure Bundler to save gems to a folder within repository directory via bundle config set path vendor/bundle
6. (Optional) Install Rake. Running gem install rake after installing Ruby should accomplish this.
   • Rake is a task runner which will enable the developer to run certain tasks such as generating fake data.
7. Install Imagemagick to enable Workshop.codes to perform image processing.
   • Note that some platforms may also need to install cwebp to handle WebP files.

Clone the repository

This should be a familiar step for experienced developers. If not, we all start somewhere, and that's nothing to be ashamed of! However, Workshop.codes may not be the best project for a first-time developer; though, in the words of Matthew Mercer, "you can certainly try."

As a reminder, creating a fork is necessary to enable you to have push permissions to a GitHub repository, which is itself a necessary prerequisite for opening a GitHub pull request. More information on how to perform a standard "fork and pull request" workflow can be found via this wonderful Gist by Chaser324.

Post-clone setup

Note: All commands should be run in the newly-cloned project directory (i.e. workshop.codes)

1. Run bundle install to install all Ruby dependencies listed in Gemfile
2. Run npm install to install all JavaScript dependencies listed in package.json and specified in package-lock.json.
3. Run bundle exec rails db:setup to initialize your databases. Please note that this will generate a significant amount of seed data, and may take some time to complete. If you prefer not to seed your database, run bundle exec rails db:create db:schema:load instead.

Smoke check

At this point, you should now be able to run bundle exec rails s or simply rails s, then, in a separate terminal window, run npx vite. If all goes well, you should now be able to visit localhost:3000 in your browser and see a local copy of Workshop.codes running!

Common problems

Can't connect to localhost:3000 using WSL

• Check the output of bundle exec rails s and see if a different port was used.
• You may need to bind to all available interfaces via bundle exec rails s -b 0.0.0.0
• WSL may sometimes fail to expose the necessary ports to the host machine. See this GitHub discussion for potential solutions, as well as this article for another potential solution.

Potential next steps

Congratulations on (hopefully) deploying a local clone of Workshop.codes!

• To further enable/configure parts of the site, consider setting some Environment variables (COMING SOON). To begin testing your local clone, see the Testing frontpage (COMING SOON).
• If you've installed Elasticsearch, set the BONSAI_URL to any random string, and run bundle exec rails create_search_indexes to generate the search indexes that the search function relies on.