Search
⌃K

Setup a dev environment

For use when testing, improving or experimenting with PlaceOS on a local machine. Use it for driver, frontend, api and infra development.

Prerequisites

Windows

When running on windows ensure docker desktop is linked to your WSL2 shell
Docker WSL2 integration
Ensure git is using unix line endings. In powershell you can run the following command:
git config --global core.autocrlf false
Set your default terminal in VS Code to your linux shell
  1. 1.
    Press control -> shift -> P
  2. 2.
    Type Terminal: Select Default Profile
  3. 3.
    select your WSL2 terminal from the dropdown
You will then want to ensure there enough resources allocated to the Linux VM

Map a network drive for GUI access

In windows it's better that GUI editors are remotely accessing the linux filesystem, versus linux being mapped to windows as the file permissions will prevent some posix actions.
  1. 1.
    In Windows Explorer you can browse to \\wsl$\
  2. 2.
    Then you should see the available Linux environments i.e. \\wsl$\Ubuntu
  3. 3.
    You can then map this to a drive letter in windows
Map a network drive
​
​
Once mapped, place all your crystal lang projects in your Linux home folder

Launch VS Code from linux

Edit your code in windows but run extensions on linux (such as your crystal tool formatter)
  1. 1.
    Install the Remote - WSL extension in VS Code
  2. 2.
    In a linux terminal, browse to the folder with your project files
  3. 3.
    run the following command: code .
  4. 4.
    This will launch VS code in windows, however the bulk of operations are occurring in linux

Other minor issues when working with WSL2

Windows doesn't recognise git symbolic links, since the development is occurring primarily in Linux this is safe to ignore: git update-index --assume-unchanged symbolic_link

Configure the partner environment

If you are only looking to develop drivers then you probably don't need the full partner environment and can skip to the next section. Have a look at the readme on the repository then run following commands.
  1. 1.
    git clone https://github.com/place-labs/partner-environment​
  2. 2.
    cd partner-environment
  3. 3.
    ./placeos start
  4. 4.
    note the credentials output by the CLI
You can now browse to https://localhost:8443/backoffice which is full functional instance of PlaceOS running on your machine.
This is good for testing drivers end to end or connecting to real devices or services.

Developing Drivers

Driver development can be performed with a lightweight spec runner​
  1. 1.
    git clone https://github.com/PlaceOS/drivers​
  2. 2.
    cd drivers
  3. 3.
    ./harness up (starts the testing UI)
  4. 4.
    ./harness down (to terminate the docker containers)
Once up you can browse to http://localhost:8085/ to start running specs against drivers.
Developing drivers

Private / 3rd party repositories

By default the spec runner is looking at public PlaceOS drivers (Feel free to contribute). However you might want to develop some private drivers for a client or manage your own repository. To do this:
  1. 1.
    In the PlaceOS/drivers repo there is a repositories folder. Clone any 3rd party driver repository in this location.
  2. 2.
    If you would like to create a new repo for a project, create a fork of our private-drivers repo this is a template repository for drivers.
Once the repository is cloned into the repositories folder it will be available in the repository selection dropdown.

Development

Please see the following resources on driver development
It's worth mentioning that drivers are applications in their own right and it's important to update dependencies. Before starting your development, in the repository folder you are working on it's worth running shards update
Previous
Configuring a default UI
Next - Tutorials
Backend
Last modified 11mo ago