Hosting a Splinter Node
Choosing a Hosting Environment
Currently, Splinter is packaged as Docker images hosted on Docker Hub. This means Splinter can be deployed anywhere a Docker image can run. Most examples will focus on Docker Compose, but if you choose to go with a Kubernetes deployment, we have an example of our gameroom demo app designed to work well with Minikube in the github repository. The arcade.yaml file can be used as a starting point for customizing your environment.
Hosting a Splinter Node
Detailed information about planning your Splinter deployment can be found in Planning a Splinter Deployment how-to document. This section summarizes some especially important information.
Network Configuration
Other nodes must be able to connect to your node on port 8044. Applications and CLIs used to manage Splinter will connect to the Splinter REST API on port 8080.
While it is technically possible to run the Splinter daemon without port
8044 open, it is not recommended. If the daemon cannot accept incoming
connections, it will not be able to receive circuit management requests from new
peers. Also, if an existing peer has disconnected, the peer will try to
reestablish a connection to splinterd
behind the firewall, which will be
unsuccessful.
If running behind a firewall without an open port is absolutely necessary, peers
can be explicitly set with the splinterd --peer
option on startup or with the
splinter configuration setting peers = [ ]
. This will cause splinterd
to try
to establish a connection with another Splinter node, whether there is a
shared circuit defined or not, and assumes that the other node will accept
incoming connections.
Persistent Volumes
Due to the ephemeral nature of Docker containers, any data not explicitly
persisted to a volume outside the container will be lost when the container is
restarted or stopped. Persisting application data will depend on the design of
the application running on Splinter, but all deployments will need to persist
splinterd’s data directory, /var/lib/splinter
. Splinter’s directories are
described in the next section.
Important splinterd Directories
/etc/splinter/
:
Default location for the Splinter configuration directory. Note: If
$SPLINTER_HOME
is set, the default location is $SPLINTER_HOME/etc/
.
/etc/splinter/certs/
:
Default location for the TLS certificate directory, which stores CA certificates
and the associated keys. Note: If SPLINTER_HOME
is set, the default location
is $SPLINTER_HOME/certs/
.
/etc/splinter/keys/
:
Default location for splinterd keys generated with splinter keygen --system
.
/var/lib/splinter/
:
Default location for the Splinter state directory, which stores the circuit
state YAML file (unless --storage
is set to memory). Note: If
$SPLINTER_HOME
is set, the default location is $SPLINTER_HOME/data/
.
Logging
Currently, splinterd only logs to stdout and stderr. Logging levels can
be increased by starting splinterd with -v
for INFO
logging, -vv
for
DEBUG
logging or -vvv
for TRACE
. Future versions will have configurable
file logging and ability to change the log level without needing to restart
splinterd
.
Splinter Keys
There are two common types of keys used with Splinter.
Keys for splinterd
(generated by running splinter keygen --system
) will be
used in a challenge-authorization feature that is currently in development.
User keys are used for signing transactions in applications and smart contracts that run on Splinter.
Splinter Registry
A Splinter registry is used to locate Splinter nodes for the purpose of creating circuits. Registries can be local, remote, or both. For the differences between the two types of registries, instructions for configuring a registry, and recommendations, see the Splinter Registry page.
Security Concerns
REST API
Splinterd’s REST API does not have built-in authorization or access control. Anyone with access to your Splinter nodes on port 8080 will have unrestricted access to the REST API. Production Splinter deployments should implement a reverse proxy to protect the REST API.
Certificates
In order to run splinterd
and create circuits over TLS, you’ll need to provide
valid X.509 certificates and the associated private keys. Any splinter node you
will be creating circuits with will need to trust the CA that signs your
certificates.
splinterd
uses both a client and a server certificate for TLS
connections.
-
The generated server certificate should have the Extended Key Usage OID for Server Authentication (1.3.6.1.5.5.7.3.1).
-
The generated client certificate should have the Extended Key Usage OID for Client Authentication (1.3.6.1.5.5.7.3.2).
For development or non-production uses, Splinter can be run in “insecure” mode with self-signed certificates. For the instructions on generating these certificates and enabling insecure mode, see Generating Insecure Certificates for Development.
Available Docker Hub Images
Splinter images are published to splintercommunity on Docker Hub.
The Splinter project produces artifacts for multiple branches compiled with different features, which can be confusing at times. This table lists the image tags and explains what each tag means.
image tag | description |
---|---|
0.3 | Most recent 0.3 release |
0.3.x | Exact 0.3 release |
latest | Alias for 0.4 |
0.4-dev | Most recent build of 0-4 branch |
0.4 | Most recent 0.4 release |
0.4-experimental | Most recent build of 0-4 branch, features=experimental |
main | Most recent build of main branch, features=default |
experimental | Most recent build of main branch, features=experimental |
0.5 | Most recent 0.5 release |
0.5.x | Exact 0.5 release |
Upgrading Splinter
Upgrading Splinter is usually as simple as updating the version number of the Splinter images in your Docker Compose file or Kubernetes manifest, then redeploying. However, breaking changes will be introduced from time to time. Comprehensive upgrade instructions for each version can be found in the Upgrading section of the Splinter website.
Troubleshooting
Circuit Creation:
Error message: T["actix-rt:worker:1"] DEBUG [splinter::admin::rest_api::actix::submit] validation failed: 02f953633bafafe622ebdec3d6d5a309cc5dd967793dexample3d2312ed4ccb599 is not registered for the requester node: alpha
This error message suggests that the key provided as the circuit admin key in the circuit proposal isn’t the key listed for this node in the node registry. Look at your Splinter registry file and make sure that the correct key is being used.