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 in a dedicated virtual machine (see manual setup)

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

1. git clone git@github.com:specklesystems/speckle-server.git or, alternatively git clone https://github.com/specklesystems/speckle-server.git
2. cd speckle-server
3. corepack enable
4. yarn
5. yarn build
6. yarn dev:docker:up
7. cp packages/server/.env-example packages/server/.env
8. cp packages/server/.env.test-example packages/server/.env.test
9. cp packages/frontend-2/.env.example packages/frontend-2/.env
10. cp packages/dui3/.env.example packages/dui3/.env
11. 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.

1. 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 😄
2. We change into the cloned repository directory.
3. Nodejs versions ^16 now come with a package manager manager bundled named corepack. It enables us to use yarn without actually installing anything.
4. 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 for yarn install bootstraps the repo.
5. 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.
6. 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.
7. 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.
8. 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
9. Similarly to the last step, we're providing sensible defaults for env variables that are applied to the new frontend
10. Similarly to the last step, we're providing sensible defaults for env variables that are applied to dui3
11. 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 (run yarn 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).