README.en.md

Hexlet SICP

Read this in another language: Русский

Hexlet SICP is a service for those studying the book Structure and Interpretation of Computer Programs. Track your progress and match yourself against others on the global leaderboard.

How to study Structure and Interpretation of Computer Programs (SICP) (in Russian)

For contributors

• Discuss the project in #hexlet-volunteers on Slack: http://slack-ru.hexlet.io (in Russian)

Recorded meetings

• Recorded meetings playlist

FAQ

Q: I get this error Illuminate\Session\TokenMismatchException: CSRF token mismatch. A: Reset your config cache php artisan config:clear

Requirements

Run composer check-platform-reqs to check PHP deps:

• PHP ^8.1
• Composer
• Node.js (v16+) & NPM (6+)
• SQLite for local, PostgreSQL for production
• heroku cli; How to deploy Laravel on Heroku (in Russian)

What is a Version Manager? (in Russian)

Setup

Local setup

To run on the local interpreter and SQLite:

make setup # set up the project
make start # start server at http://127.0.0.1:8000/
make test # run tests

Running on PostgreSQL (deployed in a Docker container)

1. Install deps and prepare the config file

   make setup

2. Put your database credentials in the .env file

   DB_CONNECTION=pgsql
   DB_HOST=localhost
   DB_PORT=54320
   DB_DATABASE=postgres
   DB_USERNAME=postgres
   DB_PASSWORD=secret

3. Start the database container and seed

   make compose-start-database
   make db-prepare

4. Run the local server

   make start

Setup in Docker

1. Prepare the .env file

   make env-prepare

2. Put your database credentials in the .env file

   DB_CONNECTION=pgsql
   DB_HOST=localhost
   DB_PORT=5432
   DB_DATABASE=postgres
   DB_USERNAME=postgres
   DB_PASSWORD=secret

3. Build and start the app

   make compose-setup # build project
   make compose-start # start server at http://127.0.0.1:8000/

   make compose-bash  # start bash session inside docker container
   make test          # run tests inside docker container

Coding stardards and other rules

• Pull requests should be as small as reasonably possible
• All code must comply with the PSR12 and Laravel standards (we also use some custom rules for added challenge)
• Every pull request must pass all tests
• All controller actions must have test coverage (Start writing (appropriate) tests (in Russian))
• The forms are made using laraeast/laravel-bootstrap-forms
• RoR's resource routing convention is used for the most part. In a very rare case when a route doesn't seem to fit the convention, it should be discussed first
• All strings must be stored in locale files
• To enable Rollbar logging, set the variable LOG_CHANNEL=rollbar and ROLLBAR_TOKEN= (docs)
• To add an exercise, put its contents (a listing or pic) at resources/views/exercise/listing/#_#.blade.php and its text description, at resources/lang/{locale}/sicp.php under the key exercises.#.# (mind the locale).
• To generate helper files (for autocompletion), use make ide-helper
• Run php artisan and check out all available commands!

GitHub Auth Setup Guide

Integrate the app with your GitHub account (read more at https://developer.github.com/apps/about-apps/). To integrate the app:

• Enter your GitHub account and go to Settings
• On the right, choose GitHub Apps, then push New GitHub App
• A form will pop up. In the GitHub App name field, type the app name (for example, Hexlet-SICP)
• In Homepage URL, put the web address hosting your deploy (for example, https://hexlet-sicp.herokuapp.com)
• In User authorization callback URL, put the URL to redirect to, once a user authorizes via GitHub. (for example, https://hexlet-sicp.herokuapp.com/oauth/github/callback)
• In Webhook URL, put the URL to dispatch events to (for example, https://hexlet-sicp.herokuapp.com/oauth/github/callback)
• Set the permission to access email (User permissions->Email addresses->Read only)
• Save the app settings (push Create GitHub App)
• The app page will open. Copy the Client ID and Client secret
• Generate a private key (push Generate a private key)

If deployed on Heroku, set the environment variables for your deploy. To set environment variables:

• Open Settings
• In the Config Vars setting, add the following variables: GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET and GITHUB_URL_REDIRECT and set them to the respective Client ID, Client secret and User authorization callback URL
• Then, reset the configuration cache: heroku run php artisan config:cache

Setting up a testing database

1. Create a separate Postgres database. Connection settings are available in the pgsql_test section of config/database.php. How to set up a test database from scratch:

   sudo apt install postgresql
   sudo -u postgres createuser --createdb $(whoami)
   sudo -u postgres createuser hexlet_sicp_test_user
   sudo -u postgres psql -c "ALTER USER hexlet_sicp_test_user WITH ENCRYPTED PASSWORD 'secret'"
   createdb hexlet_sicp_test

2. Run tests on your testing database: DB_CONNECTION=pgsql_test make test

Adding a pre-commit hook

git config core.hooksPath .githooks

This repository is created and maintained by the team and the community of Hexlet, an educational project. Read more about Hexlet (in Russian).