Lykos / cube_trainer

Website with tools to support Rubik's Cube training with a focus on blindfolded solving.
https://www.cubetrainer.org
MIT License
11 stars 4 forks source link
rails rails-api rails6 rubiks-cube rubiks-cube-timer ruby typescript

CodeQL Rubocop Ruby Typescript License: MIT

CubeTrainer

This is the repository for https://www.cubetrainer.org, which is a small website that contains some tools to support Rubik's Cube training with a focus on blindfolded solving.

Install

Clone the repository

git clone git@github.com:Lykos/cube_trainer.git
cd cube_trainer

Install OS dependencies

Postgresql

This example is what I did on Ubuntu, but I'm sure you can figure out how to install PostgreSQL on your OS, too.

sudo apt install postgresql libpq-dev

Ruby

Ruby is the programming language that is used for the CubeTrainer backend. If you only want to run the frontend, this dependency might not be necessary, but note that the frontend alone cannot do a lot, so this is only useful if you want to contribute something where the backend really isn't relevant.

You can install Ruby via any means you prefer. We recommend installing Ruby via rbenv. This is a tool that lets you manage different Ruby versions. Check the first few lines in the Gemfile for the Ruby version that should be used for CubeTrainer. Other versions might work as well, but there is no guarantee.

You can try to use the Ruby installation that comes via your OS package manager, too, but there is a good chance that this will be an older Ruby version that won't work.

Node.js and NPM

NPM is the package manager and toolchain we use for the CubeTrainer frontend and Node.js is the JavaScript runtime that NPM uses. If you only want to run the backend, this dependency might not be necessary, but note that the backend alone cannot do a lot, so this is only useful if you want to contribute something where the frontend really isn't relevant.

You can install Node.js and NPM via any means you prefer. We recommend installing it via nvm. This is a tool that lets you manage different Node.js and NPM versions. Check the first few line of the package.json (look for the string "engines") for the Node.js and NPM versions that should be used for CubeTrainer. Other versions might work as well, but there is no guarantee.

You can try to use the Node.js and NPM installation that comes via your OS package manager, too, but there is a good chance that this will be older versions that won't work.

Filemagic

At the moment, cube trainer depends on the ruby-filemagic Gem that depends on the C magic library. We are trying to get rid of this, but while it is still active, you need to install it. This is what I did on Ubuntu:

sudo apt install libmagic-dev

Mailcatcher (optional)

Optionally, you can install mailcatcher. This is a useful tool to debug emails that the website sends. Note that the documentation of mailcatcher recommends to set it up separately as a global gem and to not make it a gem dependency.

gem install mailcatcher

Install Ruby & JS dependencies

Using Bundler and npm:

bundle install && npm install

Setup DB User

sudo su - postgres
createuser cube_trainer -d -E -P
cube_trainer
exit

Initialize the database

bundle exec rake db:create db:migrate

Build the frontend

bundle exec rails npm:build

Run tests

bundle exec rails spec

Run frontend tests

bundle exec rails npm:test

Run server

The best way to start all the necessary processes is to install overmind and then to simply run:

overmind start

Alternatively, you can run these commands in separate terminals. Mailcatcher is optional and only needed if you want to debug emails.

bundle exec rails npm:start
bundle exec rails server
mailcatcher # optional

Now you can access the site at http://localhost:4200. Note that accessing it via http://localhost:3000 might also work, but you won't get automatic refreshes on TypeScript changes, so it's not recommended.

Dependencies

For the full list of dependencies, please check the Gemfile and the package.json, but the most relevant ones are listed here:

For development, there are these relevant dependencies:

Note that the way we combine Angular and Ruby is a bit self-baked. They basically live in different directories and the only connection is a hand-crafted Rails controller that serves the index.html file compiled by Angular. We previously tried to use various other ways to integrate them. Some of them worked, but they were a huge pain, so we went for this handcrafted solution. The problems we encountered with other integrations included:

Production Setup

The website is hosted on Heroku and is automatically deployed if CI on the master branch on Github passes. It uses the following Heroku plugins.

Formerly it also used Redis-to-go for ActionCable. Redis-to-go was removed from Heroku in August 2023 and we don't have a replacement yet. I.e. the ActionCable related things don't work at the moment. Luckily, they are only used to notify the user of achievements, so it's not removing a lot of functionality.

Using the Website

Navigate to https://www.cubetrainer.org/signup to create an account. After the signup process, you can log in via https://www.cubetrainer.org/login and then create training sessions in https://www.cubetrainer.org/modes. What the website is best at is training blind algs with smart sampling that will show you algorithms more that you don't know well.

Background

This website started as a bunch of command line scripts that helped me practicing and eventually I added a database, than a small web frontend and eventually I turned it into a full website. The entire backstory can be found in https://www.cubetrainer.org/about.