Using the Platform SDK locally
The SpatialOS CLI ships with a local API service. This runs as a background daemon on your machine, and allows you to use the Platform SDK to develop tools for local deployments.
You can use the SpatialOS CLI commands to interact with the local API service.
Example: basic local workflow
1. Start the local API service
To start an instance of the local API service, navigate to your project’s root directory and run spatial service start
.
To start a local API service instance from outside your project’s directory structure, or if your main configuration file (usually called spatialos.json
) isn’t in the project root, you can specify it by passing the --main_config
flag.
For example:
# Will run on port 9876 and attempt to find a spatialos.json file in this directory.
spatial service start
# Will run on port 1234, using the project configuration at the provided path.
spatial service start --port 1234 --main_config path/to/project/spatialos.json
2. Connect to the local API service
Use the normal ServiceClient
creation methods (such as DeploymentServiceClient.Create
), but specify a PlatformApiEndpoint
that points to your locally running instance of the local API serice. This must include:
- the hostname “localhost”
- the port your instance is running on
insecure: true
(because the local API service does not support TLS connections)
For example:
var localApiPort = 9876;
var localApiEndpoint = new PlatformApiEndpoint("localhost", localApiPort, insecure: true);
var deploymentServiceClient = DeploymentServiceClient.Create(localApiEndpoint);
var snapshotServiceClient = SnapshotServiceClient.Create(localApiEndpoint);
3. Check the status of the service
You can get information on the running local API service instance, if it exists, using spatial service status
.
You can run this command from anywhere - you don’t need to be in a project directory.
4. Start a local deployment
You need to provide:
- your project name
- a name for your deployment
- a launch configuration file, supplied as JSON
For example:
var createdDeployment = deploymentServiceClient.CreateDeployment(new CreateDeploymentRequest
{
Deployment = new Deployment
{
ProjectName = projectName,
Name = deploymentName,
LaunchConfig = new LaunchConfig
{
ConfigJson = "your launch config"
}
}
}).PollUntilCompleted().GetResultOrNull();
5. Take a snapshot of the running deployment
You need to provide:
- the project name
- the deployment name you chose in step 4
For example:
var latestSnapshot = snapshotServiceClient.TakeSnapshot(new TakeSnapshotRequest
{
Snapshot = new Snapshot
{
ProjectName = createdDeployment.ProjectName,
DeploymentName = createdDeployment.Name
}
}).PollUntilCompleted().GetResultOrNull();
6. Stop the deployment
You need to provide:
- the deployment ID (the unique identifier for this particular run of the deployment; you can find this on the
Deployment
object) - the project name
For example:
deploymentServiceClient.StopDeployment(new StopDeploymentRequest
{
Id = createdDeployment.Id,
ProjectName = createdDeployment.ProjectName
});
7. Stop the local API service
To shut down the running local API service instance, run spatial service stop
.
Stopping the local API service also shuts down any locally running deployment that was started with the local API service.
Accessing log files
You can find the deployment and service log files in <project>/logs/<deployment_name>/<date_and_time_of_deployment>/
.
For more information about log files and how to change log file location, see Logging with the SpatialOS CLI.