Advanced Usage

Use vagrant directly

Run vagrant commands directly instead of through THEO:

  • or directly via Vagrant's cli (bash commands run from the root of the repository):
    export OPENDUT_REPO_ROOT=$(git rev-parse --show-toplevel)
    export VAGRANT_VAGRANTFILE=$OPENDUT_REPO_ROOT/.ci/docker/Vagrantfile
    vagrant up
  • provision vagrant with desktop environment
    ANSIBLE_SKIP_TAGS="" vagrant provision

Re-provision the virtual machine

This is recommended after potentially breaking changes to the virtual machine.

  • Following command will re-run the ansible playbook to re-provision the virtual machine. Run from host:
cargo theo vagrant provision
  • Destroy test environment and re-create it, run within the virtual machine:
cargo theo vagrant ssh
cargo theo testenv destroy
cargo theo testenv start

Cross compile THEO for Windows on Linux

cross build --release --target x86_64-pc-windows-gnu --bin opendut-theo
# will place binary here

Proxy configuration

In case you are working behind a http proxy, you need additional steps to get the test environment up and running. The following steps pick up just before you start up the virtual machine with vagrant up. A list of all domains used by the test environment is reflected in the proxy shell script: .ci/docker/vagrant/ It is important to note that the proxy address used shall be accessible from the host while provisioning and within the virtual machine.

If you have a proxy server on your localhost you need to make this in two steps:

  • Use proxy on your localhost

    • Configure vagrant to use the proxy localhost.
      # proxy configuration script, adjust to your needs
      source .ci/docker/vagrant/ http://localhost:3128
    • Install proxy plugin for vagrant
      vagrant plugin install vagrant-proxyconf
    • Then starting the VM without provisioning it. This should create the vagrant network interface with network range
      vagrant up --no-provision
  • Use proxy on private network address

    • Make sure this address is allowing access to the internet:
      curl --max-time 2 --connect-timeout 1 --proxy
    • Redo the proxy configuration using the address of the host within the virtual machine's private network:
      # proxy configuration script, adjust to your needs
      source .ci/docker/vagrant/
    • Reapply the configuration to the VM
      $ vagrant up --provision
      Bringing machine 'opendut-vm' up with 'virtualbox' provider...
      ==> opendut-vm: Configuring proxy for Apt...
      ==> opendut-vm: Configuring proxy for Docker...
      ==> opendut-vm: Configuring proxy environment variables...
      ==> opendut-vm: Configuring proxy for Git...
      ==> opendut-vm: Machine not provisioned because `--no-provision` is specified.
  • Unset all proxy configuration for testing purposes (non-permanent setting in the shell)

    unset http_proxy https_proxy no_proxy HTTP_PROXY HTTPS_PROXY NO_PROXY
  • You may also set the docker proxy configuration in your environment manually:

    • ~/.docker/config.json
        "proxies": {
          "default": {
            "httpProxy": "http://x.x.x.x:3128",
            "httpsProxy": "http://x.x.x.x:3128",
            "noProxy": "localhost,,netbird-management,netbird-dashboard,netbird-signal,netbird-coturn,keycloak,edgar-leader,edgar-*,carl,"
    • /etc/docker/daemon.json
        "proxies": {
          "http-proxy": "http://x.x.x.x:3128",
          "https-proxy": "http://x.x.x.x:3128",
          "no-proxy": "localhost,,netbird-management,netbird-dashboard,netbird-signal,netbird-coturn,keycloak,edgar-leader,edgar-*,carl,"

Custom root certificate authority

This section shall provide information on how to provision the virtual machine when running behind an intercepting http proxy. This is also used in the docker containers to trust the custom certificate authority. All certificate authorities matching the following path will be trusted in the docker container: ./resources/development/tls/*-ca.pem.

The following steps need to be done before provisioning the virtual machine.

  • Place certificate authority file here: resources/development/tls/custom-ca.crt
  • Optionally, disable private network definition of vagrant, if this causes errors.
export CUSTOM_ROOT_CA=resources/development/tls/custom-ca.pem
vagrant provision