Quickstart: Set up a LibreCores development environment

Note

All documentation assumes that you’re running Linux. Unless noted otherwise, we have tested Ubuntu 16.04 and openSUSE Tumbleweed. If you’re running another operating system or version, please get in touch when you run into trouble. Note that a Linux installation inside a virtual machine (VM) is usually not sufficient as the development environment runs inside a VM itself.

Step 1: Get the code from git

First, you need to get the current development code from Git.

cd your_preferred_code_directory
git clone https://github.com/librecores/librecores-web.git

Note

Throughout the documentation, most file paths will be given relative to the directory where you cloned the librecores-web repository.

Step 2: Provide secrets

LibreCores communicates with some third-party APIs, such as GitHub or Google, for user logins and other things. To talk to these APIs, personalized API keys (“secrets”) are needed.

First, copy the default secrets file as starting point:

cp ansible/secrets.dist/dev-vagrant.secrets.yml ansible/secrets/dev-vagrant.secrets.yml

Open the ansible/secrets/dev-vagrant.secrets.yml and follow the instructions in there to get a custom API key for the various providers.

At minimum, we require:

  • GitHub for repository crawling
  • Algolia for search

You can disable algolia by setting NullEngine as suggested in their documentation.

Step 3: Set up the development environment

LibreCores uses Vagrant and Ansible to provide a development environment that’s very similar to our production environments. To simplify the setup of all necessary components, we provide a bootstrap script for Ubuntu and openSUSE. Simply run

./bootstrap-dev.sh

to install all dependencies and get started.

Alternative version of step 3: Manually installing the development environment

If you’re not using openSUSE or Ubuntu, you need to manually install and configure the required dependenies.

  • Install VirtualBox, if you don’t already have it installed.
  • Install Ansible >= 2.0
  • Install the NFS server packages. If you don’t want to, see the note on NFS below.
  • Install Vagrant. It’s fast and simple: http://www.vagrantup.com/downloads.html
  • Install vagrant-hostmanager: vagrant plugin install vagrant-hostmanager
  • cd vagrant; vagrant up. This might take a while.
  • Take your web browser to http://librecores.devel and you should see the LibreCores web site.

A Note on NFS

NFS is used by Vagrant for sharing the development files between your host and the VM. NFS is the most reliable and performant way, but requires a bit more setup.

If you use NFS, …

  • Install the NFS server on the host machine. Usually the package is named nfs-kernel-server.
  • Make sure that the daemon runs (sudo sytemctl status nfs-server)
  • Disable any firewall rules preventing access from vboxnet devices to the NFS ports. On openSUSE, by default the “ext” firewall rule is applied, preventing access. The easiest way is to disable the firewall completely.

If you don’t use NFS, …

  • Open the file vagrant/Vagrantfile and uncomment the corresponding lines of configuration.

Customizing Vagrant Configuration

If you need to customize Vagrant configuration, such as adding networks or you can add a Vagrantfile.private under the vagrant folder with your customizations. However, not all settings in Vagrantfile can be overridden.

Example: The following configuration uses SSHFS in place of NFS (you need to disable NFS in your host though) and attaches the VM to a bridged network to acquire a public IP.

Vagrant.configure("2") do |config|
    config.vm.synced_folder ".",  "/vagrant", id: "vagrant-root",type: 'sshfs'
    config.vm.synced_folder "..", "/var/www/lc", id: "application", type: 'sshfs'
    config.vm.define 'librecores' do |node|
        node.vm.network :public_network, ip: '10.42.0.99'
    end
    config.vm.provider :virtualbox do |v|
        v.cpus = 2
        v.memory = 2048
    end
end

Step 4: Develop!

Now that all setup is done, you can start developing. First, point your web browser to http://librecores.devel. This will open the development version of LibreCores running on your machine. Whenever you make a code change, a simple reload of the page in your browser is usually sufficient to show the changes.

Note

By default, two test users are created which you can use to log in: user “test” with password “test”, and user “test2” with password “test2”.

Happy coding!