README

Dependencies

• Ruby 3.3
• Rails 7.2
• Redis
• PostgreSQL

If you are not acquainted with Rails, it may help to go through the Getting Started with Rails tutorial for Rails 7.1. If you wish to learn Ruby, try out the quickstart guide provided on their website, or if you are already acquainted with various programming languages, try the Learn X in Y minutes tutorial for Ruby.

This README mostly focuses on how to get started developing this project with Docker – in any environment with Docker installed you should be able to have the Glowfic server up and running.

Setup Process

Cloning the repository

• Ensure you have Git installed:

  sudo apt-get install git on Ubuntu

  sudo pacman -S git on Arch Linux

• Clone the repository

  • Enter a folder you want to clone the code to:

    cd ~/Documents

  • Copy the code:

    git clone https://github.com/glowfic-constellation/glowfic.git

(More specific details, such as if you have write permission and wish to use SSH instead of HTTPS, may be found on the GitHub site.)

Setting up the Glowfic site environment

If you haven't already, start by installing Docker and Docker Compose.

Then run docker compose up within the glowfic directory. This will set up a Postgres server, a Redis server, and a Glowfic app server which can talk to both of them.

There are some scripts for interacting with the Glowfic server in bin-docker. You may want to add them to your PATH. If you want, you can use direnv to ensure that they're on your path only when you're in the glowfic server. In any case, you'll use the rake and rails commands in that directory to set up and start the server.

If you have added these scripts to your PATH you can leave off "bin-docker/" in any commands that follow.

Setting up the database

Once you've taken these steps, you should be able to set up the contents of the glowfic database with some example data:

• bin-docker/rake db:setup

This will set up the database and add some sample information – currently these are users, continuities, characters, galleries, icons and templates, and some posts and replies.

If you encounter an error involving the 'citext' extension:

• Ensure the postgres container is running, with docker compose up postgres &
• Execute docker compose exec postgres psql, and then in the prompt that appears:
• CREATE EXTENSION IF NOT EXISTS citext;

You will need to re-run bin-docker/rake db:migrate.

Executing the server

The server should have started itself when you ran docker compose up. When it's started, go to http://localhost:3000/, where you should see a local copy of the Constellation. To stop the server, either close the Terminal or use Ctrl+C to stop the process.

Running tests

To run tests, go to the root of the directory (the 'glowfic' folder) and execute the command:

• bin-docker/rake spec.

This will go through the rspec tests.

If you encounter a PG::UndefinedTable error, mentioning that a relation doesn't exist, ensure you've also migrated your test database. This can be done with:

• docker compose run -e RAILS_ENV=test web rake db:migrate

After this, you should be able to re-run the tests.

Staying up to date

The code updates quite frequently. To make sure you're using and developing against the latest version, you'll need to download the updated copy, update the gems, and possibly even update your version of Ruby.

First, go to the glowfic folder and download the latest code:

• git pull

Then look at the Gemfile file, where it states the version of Ruby, to make sure it hasn't changed. If it has changed, you can rebuild the glowfic image with:

• docker compose stop
• docker compose build
• docker compose up

Now, update the gems used for the project:

• bin-docker/bundle

And finally, run any database migrations that might have been added in the meantime:

• bin-docker/rake db:migrate

You should now be able to execute the server, as before but now with the latest updates.

Validation tools

We use the following tools to make sure our code is clean and standards-ctompliant:

• html-proofer
• The W3 HTML validator
• traceroute
• rails_best_practices
• sass-lint

We run the following tools through github actions:

• brakeman
• ESLint
• haml-lint
• Rubocop

CodeClimate runs the following tools automatically:

• bundler-audit
• duplication
• fixme

Tools we do not currently use but are interested in evaluating:

• bullet
• Reek and Flog if they're not already included by CodeClimate or other gems (Marri's brain thinks they might be, the way flay is in duplication, but isn't citing its sources)
• Reek's brother and sister gems

Backstop - UI validation

We use BackstopJS to run regression tests on the UI + CSS.

Before each test, we automatically run script/before_backstop.rb to set up a consistent environment. To perform a test:

# you may wish to recreate + reseed your database for consistent images:
# bin-docker/rails db:reset

# set the layout you want to validate
export LAYOUT=starrylight

# switch to the branch you want to use as a reference
git switch main
# create reference images and save them to backstop/
bin-docker/backstop reference $LAYOUT

# switch to the branch you want to test
git switch feature/update-css
# validate the layout against the reference images
bin-docker/backstop test $LAYOUT

# see a list of other commands you can run:
bin-docker/backstop --help
# view a report in your browser:
open backstop/reports/$LAYOUT/index.html
# promote the images to reference images if the changes are intentional:
bin-docker/backstop approve $LAYOUT

Attribution

We make use of the famfamfam silk pack of icons, which is licensed under a Creative Commons Attribution license, including some icons that have been modified from the originals. These can be found in various locations, including in the dropdown menu in posts.