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.
Last updated
For use when testing, improving or experimenting with PlaceOS on a local machine. Use it for driver, frontend, api and infra development.
Last updated
WSL2 if running Windows
When running on windows ensure docker desktop is linked to your WSL2 shell
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
Press control -> shift -> P
Type Terminal: Select Default Profile
select your WSL2 terminal from the dropdown
You will then want to ensure there enough resources allocated to the Linux VM
https://docs.microsoft.com/en-us/windows/wsl/wsl-config#example-wslconfig-file
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.
In Windows Explorer you can browse to \\wsl$\
Then you should see the available Linux environments i.e. \\wsl$\Ubuntu
You can then map this to a drive letter in windows
Once mapped, place all your crystal lang projects in your Linux home folder
Edit your code in windows but run extensions on linux (such as your crystal tool formatter)
Install the Remote - WSL extension in VS Code
In a linux terminal, browse to the folder with your project files
run the following command: code .
This will launch VS code in windows, however the bulk of operations are occurring in linux
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
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.
cd partner-environment
./placeos start
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.
Driver development can be performed with a lightweight spec runner
git clone https://github.com/PlaceOS/drivers
cd drivers
./harness up (starts the testing UI)
./harness down (to terminate the docker containers)
Once up you can browse to http://localhost:8085/ to start running specs against drivers.
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:
In the PlaceOS/drivers repo there is a repositories folder.
Clone any 3rd party driver repository in this location.
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.
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
