Please go through the Contribution Guidelines before going forward with any development. This helps us keep the process streamlined and results in better PRs.
If you have any setup problems, please ensure you have read through all the instructions have all the required software installed before creating an issue.
There are several ways to run your own instance of CircuitVerse:
Gitpod is a free platform that allows you to develop CircuitVerse in a cloud VS Code environment.
Instructions are available in our wiki and pull requests can be created following these steps.
Docker can be used to create virtual machines on your PC so you don't have to setup dependencies (e.g. PostgreSQL and Redis) manually.
Note: Please follow these instructions for installing Docker on Windows 10 Home
- Run
docker-compose upto run the instance - Run
docker-compose downto stop the instance - Run
docker-compose build --no-cacheto rebuild the instance (make sure the instance is not running first)
Note: PostgreSQL and Redis must be running. PostgreSQL must be configured with a default user
- Git - using a GUI such as SourceTree or GitHub Desktop can help.
- Ruby on Rails (
ruby-2.6.5&Rails 6.0.1) - PostgreSQL (
9.5) - Database - Yarn - JavaScript package manager
- Redis - Data structure store
- ImageMagick - Image manipulation library
Redis can be installed from the MicrosoftArchive Redis repository.
It can also be run natively or through Docker Desktop if you have the Windows Subsystem for Linux (WSL) enabled.
To clone the repository, either use the Git GUI if you have one installed or enter the following commands:
git clone https://github.com/CircuitVerse/CircuitVerse.git
cd CircuitVerseNote: If you want to contribute, first fork the original repository and clone your forked repository into your local machine. If you don't do this, you will not be able to make commits or change any files.
git clone https://github.com/<username>/CircuitVerse.git
cd CircuitVerse- Install Ruby bundler :
gem install bundler - Install Ruby dependencies:
bundle install - Install Yarn dependencies:
yarn - Configure your PostgreSQL database in
config/database.yml(copyconfig/database.example.ymlfor the template)- Note: The Postgres credentials need to be updated to your currently running database
- Create database:
rails db:create - Run database migrations:
rails db:migrate - Start Sidekiq (background processes & job queue):
bundle exec sidekiq -e development -q default -q mailers -d -L tmp/sidekiq.log - ./bin/webpack-dev-server for Hot Module reload for fast development or transpile using ./bin/webpack.
Then, local development can be started with rails s -b 127.0.0.1 -p 8080. Navigate to 127.0.0.1:8080 in your web browser to access the website.
Additional instructions can be found here and there are some extra notes for single user installations:
- If you are facing difficulties installing RVM, most probably it is because of an older version of rvm shipped with Ubuntu's desktop edition and updating the same resolves the problem.
- Run Terminal as a login shell so ruby and rails will be available.
To setup CircuitVerse API documentation, refer docs/README.md
Yarn is a package manager for the JavaScript ecosystem. CircuitVerse uses Yarn for frontend package and asset management.
- Removing RVM
sudo apt-get --purge remove ruby-rvm sudo rm -rf /usr/share/ruby-rvm /etc/rvmrc /etc/profile.d/rvm.sh - Installing new version of RVM
curl -L https://get.rvm.io | bash -s stable --ruby --autolibs=enable --auto-dotfiles - If you are facing errors running the
rails db:createensure that the socket file(i.emysql.sock) is present in that location. Some possible locations where it might be present is/run/mysqld/mysqld.sockor/var/lib/mysql/mysql.sock.
Heroku is a free cloud platform that can be used for deployment of CircuitVerse
You will be redirected to the Heroku page for deployment on clicking the below button. Make sure that you fill in the Config Vars section before deploying it.
To seed the database with some sample data, run bundle exec rake db:seed. This will add the following admin credentials:
User: Admin
Email: [email protected]
Password: password
You can include binding.pry anywhere inside the code to open the pry console.
CircuitVerse uses webpack to bundle the javascript module and assets. To see any changes made to the simulator code without refreshing (hot reload), start bin/webpack-dev-server
The following commands should be run for production:
bundle install --with pg --without development test
RAILS_ENV=production bundle exec rake assets:precompile
bundle exec sidekiq -e production -q default -q mailers -d -L tmp/sidekiq.log
Before making a pull request, it is a good idea to check that all tests are passing locally. To run the system tests, run bundle exec rspec or bin/rake spec:all
Note: To pass the system tests, you need the Chrome Browser installed.
CircuitVerse API uses RSASSA cryptographic signing that requires private and associated public key. To generate the keys RUN the following commands in CircuitVerse/
openssl genrsa -out config/private.pem 2048
openssl rsa -in config/private.pem -outform PEM -pubout -out config/public.pem
The .env file only needs to be used if you would like to link to third party services (Facebook, Google, GitHub, Slack, Bugsnap and Recaptcha)
- Create an app on the third party service (instructions)
- Make the following changes in your Google, Facebook or Github app:
- Update the
site urlfield with the URL of your instance, and update thecallback urlfield with<url>/users/auth/google,<url>/users/auth/facebookor<url>/users/auth/githubrespectively.
- Update the
- Configure your
idandsecretenvironment variables in.env. If.envdoes not exist, copy the template from.env.example. - After adding the environment variables, run
dotenv rails serverto start the application.