Environment Setup
Complete guide to get Speckle server running locally for development, testing, and contribution
Development vs Production: This setup is for development and testing only. For production deployment, use the Docker Compose or Kubernetes guides.
Project Structure
The Speckle server is organized as a monorepo with the following key packages:
packages/server
: Main API server (Node.js)packages/frontend-2
: Web interface (Vue.js)packages/viewer
: 3D viewer (Three.js)packages/preview-service
: Preview image generationpackages/webhook-service
: Webhook processingpackages/fileimport-service
: File import processing
Prerequisites
Before setting up your development environment, ensure you have:
- Git for version control
- Node.js (check package.json engines field for version requirements)
- Docker and Docker Compose for containerized services
- GitHub SSH key (optional, for SSH-based cloning)
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).
Setup Instructions
To run a barebones Speckle Server, you need to run:
- the
frontend-2
package (Vue.js web interface) - the
server
package (Node.js API server)
Optionally, to enable extra functionality, microservices should be run separately:
- the
preview-service
package generates preview images for streams - the
webhook-service
package is responsible with calling the configured webhooks - the
fileimport-service
package parses and imports uploaded files into Speckle
Clone and setup repository
Start dependencies
Configure environment files
Start development server
Wait for the frontend to build
Wait for the Vue.js frontend to build, and you have a fully functional Speckle
Server running at http://localhost:3000
.
Don’t forget to set up the variables in the .env
& .env.test
files
according to your deployment
In this deployment type, the Vue.js frontend 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 Node.js server component will listen on the local interface (not available over the network) on port 3000
, and will proxy the frontend requests to the Vue.js frontend component (as configured in .env file).
Getting Help
- Community Forum: speckle.community
- GitHub Issues: speckle-server issues