# Local Development Environment
This is the recommended method for developing or debugging the Speckle Server locally.
If you plan to give others access to your Server instance, consider running it with production settings. Please refer to our guide for Kubernetes or Docker Compose.
# TL;DR
# Prerequisites
Assuming you have:
- git (opens new window)
- optional GitHub configured with ssh key auth (opens new window).
- Node 18 (opens new window).
- Docker (opens new window) and Docker Compose (opens new window).
Also don't worry if you don't have all of these, the detailed instructions provide more info on alternative ways to achieve the same thing. This is a high efficiency getting started step list.
# Supported Platforms
Speckle server has been developed on Linux, Windows WSL2, and MacOS. It does not work on Windows without WSL2.
On MacOS devices with Apple based chips (M2, M3 etc.) it is possible to run the server as described below, but building and running Dockerfiles takes a lot of time (due to emulation of an x86 platform).
# Steps
git clone [email protected]:specklesystems/speckle-server.git
or, alternativelygit clone https://github.com/specklesystems/speckle-server.git
cd speckle-server
corepack enable
yarn
yarn build
yarn dev:docker:up
cp packages/server/.env-example packages/server/.env
cp packages/server/.env.test-example packages/server/.env.test
cp packages/frontend-2/.env.example packages/frontend-2/.env
cp packages/dui3/.env.example packages/dui3/.env
yarn dev
Wait for the frontend to build, and voila, you have a fully functional Speckle Server running at http://localhost:3000 (opens new window).
To run a specific part of the Speckle server stack, go to the components section
# Details
Let's step back and see what we did.
- To clone the repo git with ssh key (opens new window) auth was used.
You can use https based auth too, and can also gather some bonus points by using the
gh-cli
😄 - We change into the cloned repository directory.
- Nodejs versions ^16 now come with a package manager manager bundled named
corepack
. It enables us to use yarn without actually installing anything. - The monorepo is managed by yarn workspaces (opens new window).
This way the package manager handles dependencies of the monorepo and the proper connections between the different packages.
Running
yarn
a shorthand foryarn install
bootstraps the repo. - Some of the local packages (viewer, object loader) has to be built the first time so that all packages are linked properly.
This can be done easily with a yarn script, where the yarn command will execute the given build script in all packages where it exists.
So running
yarn build
triggers all available build commands. - In this step, all the required services are started via docker compose.
The
docker-compose-deps.yml
file contains a sensible default setup of all the required non Speckle developed services. This config by no means meant to be used in production. If you are not running these dependencies via docker compose, please make sure, that their configuration options are in line with either the compose file or the individual package configurations. - In this step the provided example file is copied to a
.env
file with keeping the default values. Here again we are providing a set of sensible defaults that work out of the box if you follow this guide, but do make sure to reflect any changes you make in you environment. - Similarly to the last step, we're providing sensible defaults for env variables that are applied when running tests or running the server in test mode
- Similarly to the last step, we're providing sensible defaults for env variables that are applied to the new frontend
- Similarly to the last step, we're providing sensible defaults for env variables that are applied to dui3
- Just like above, we use yarn to run the
dev
script in each package. This is probably not the most efficient way, since it starts more packages in development mode, than needed, but its the easiest command that gets a server up and running. When developing, you probably want to run each component separately. A good enough setup might be to just run the server and the preferred frontend (runyarn dev
only in those individual package directories).
When running yarn dev
for all packages you might see errors relating to @speckle/shared
being missing, but this is only temporarily because @speckle/shared
is also being re-built at that point in time. Once its finished building all of the other packages should pick up on it and work fine. You might also see GraphQL Codegen errors, which also are temporary, because they rely on the speckle server being up and running.
IMPORTANT
Don't forget to set up the variables in the .env
& .env.test
files according to your deployment
# Components
To run a barebones Speckle Server, you need to run:
- the
frontend-2
package (see the readme.md file in the git repo (opens new window)) - the
server
package (see the readme.md file in the git repo (opens new window))
Optionally, to enable extra functionality, microservices should be run separately. For more information, check their README.md
file in the git repository:
- the
preview-service
package generates preview images for streams (see the readme.md file in the git repo (opens new window)) - the
webhook-service
package is responsible with calling the configured webhooks - the
fileimport-service
package parses and imports uploaded files into Speckle.
Detailed instructions for running them locally are kept up to date in their respective readme.md
files.
In this deployment type, the frontend Vue app will listen by default on the local interface (not available over the network) on port 8080
, but will have no knowledge about the server
component, and thus should not be accessed directly.
The server component will listen on the local interface (not available over the network) on port 3000
, and will proxy the frontend requests to the frontend component (as configured in .env file).