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
WSL2 if running Windows
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
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.
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
Launch VS Code from linux
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
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.
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.
Developing Drivers
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.
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:
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.
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
Last updated