Quickstart: Set up a LibreCores development environment¶
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
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
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
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/Vagrantfileand 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.
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”.