This documentation covers everything you need to know to quickly get your TemporalX server up and running. If this is your first time installating TemporalX, this is the documentation you should be reading.
Table Of Contents
Installation And License Registration
To install TemporalX, all you have to do is take the binary that you download and place it in a location that you can execute commands from. Typically this is somewhere in the
$PATH variable but you’ll want to consult the manual for your specific operating system. We recommend that you name the executable
Before you can use TemporalX, you need to register a license key. When purchasing TemporalX you’ll be given a unique identifier called a UUID. To register TemporalX you need to set the identifier under the environment variable
TEMPORAL_UUID. For example, if your UUID is 1, you would want to set
TEMPORAL_UUID=1. After this run the command
tex-cli and you’ll go through the registration process automatically.
You only need to register TemporalX the first time you run it on a machine. Each license is restricted to the machine it is registered on, and during the license registration process, both the license key and uuid get saved to the
.temporalx of your home directory.
If you use systemd we have a systemd service file that you can use to handle starting/stopping TemporalX:
[Unit] Description=temporalx enterprise ipfs client After=network.target [Service] User=temporalx Group=temporalx Type=simple LimitNOFILE=65535 PIDFile=/var/run/temporalx.pid ExecStart=/boot_scripts/temporalx_management.sh server KillSignal=SIGINT [Install] WantedBy=multi-user.target
And the TemporalX management script
#! /bin/bash # used to manage a TemporalX installation CONFIG_FILE="/boot_scripts/temporalx.yml" case "$1" in server) tex-cli --config "$CONFIG_FILE" --bp server ;; esac
The command line client is called
tex-cli, and invoking the command without any arguments, or with the
-h flag will display the following information:
Note: where it says
<VERSION> will be the git release tag when the binary was built, this is from
NAME: tex-cli - TemporalX command-line management tool USAGE: tex-cli [global options] command [command options] [arguments...] VERSION: <VERSION> AUTHORS: Alex Trottier <firstname.lastname@example.org> George Xie <email@example.com> COMMANDS: admin admin commands util generalized utility functions client gRPC client subcommands config configuration management tools replication, rep Create, update, and monitor replications server run the gRPC api server node runs a standalone node without the API license license management help, h Shows a list of commands or help for one command GLOBAL OPTIONS: --bootstrap, --bp bootstrap against public ipfs (default: false) --bootstrap.periodic, --bpp enables periodic reboostrapping (default: false) --bootstrap.periodic.interval value, --bppi value how often to run periodic rebootstrapping (default: 2m0s) --config PATH, --cfg PATH load the configuration file at PATH (default: "./config.yml") --config.env, --cfg.e load configuration file from environment variables (default: false) --help, -h show help (default: false) --version, -v print the version (default: false)
Make sure you always use a hex encoded private key that is either generated by the tex-cli binary during config initialization, or by yourself securely offline. Do not use any of the ones in the documentation because they are publicly available. These private keys are ed25519 keys as generated by the
go-libp2p-core crypto library, except they are also hex encoded. For more information you can consult the configuration reference manual to view a detailed breakdown of every single configuration setting.
To create a yaml configuration file, you can use the command:
$ tex-cli config generate
To populate a default configuration file in your curent directory named
config2.yml, run the command:
$ tex-cli --config config2.yml config generate
While the basic configuration file is suitable for running TemporalX, it purposely leaves a lot of configurations that aren’t specified, so that sensible defaults may be used. That being said, TemporalX has very tunable configuration parameters, that if you are familiar with IPFS, and TemporalX can be used to optimize your performance, and get a configuration profile suitable for your environment. To better showcase how a full configuration file can be used, we provide an optional parameter supplied when generating the configuration file that will showcase all the options and how they can be used. It is inadvisable to use this configuration file as is, but it certainly can be done.
$ tex-cli config generate --example.config
Starting The Node
To start the node with the config file located at
$ tex-cli --config /tmp/config.yml server
If you want to bootstrap against the public libp2p bootstrap servers, and Temporal’s public IPFS infrastructure, use the
--bp flag like so:
$ tex-cli --config /tmp/config.yml --bp server
This bootstrap process is done in the background, and does not block the startup process.
Stopping The Node
To stop the node after running the server, you can use any of the following os calls and system calls against the tex-cli server process, such as
kill -9 or
CTRL+C in the terminal window you are running the server from. This will trigger a graceful shutdown of the node which can take up to 30 seconds.
Do not abort the process unless you want to face possible data corruption. If you do need ot abort the shutdown process, waiting about 10-15 seconds after the shutdown process is started generally is enough to wait for all internal process to finish, but it is recommmended to wait the full 30 seconds it is required which typically only happens with pending gRPC calls.
TemporalX includes additional bootstrap capabilities to ensure that you can always maintain a healthy set of connected peers. Along with the basic
--bootstrap,--bp flags which does a one time connection to a preset list of peers, and starts the DHT bootstrap function which is responsible for maintaining the routing table, there is an optional “periodic bootstrap” functionality.
This periodic bootstrap functionality will run at a user-configurable interval (default of 2 minutes), and every iteration will connect to the default bootstrap peer list containing approximately 30 peers, as well as 10 randomly selected peers from our peerstore. This provides a very lightweight method of staying connected to a number of different peers, and in practice TemporalX nodes using periodic bootstrap will be much better connected than go-ipfs.
As noted by the following output with the TemporalX node not being online for more than minutes, and go-ipfs having approximately 1 week uptime, the TemporalX node is much better connected than go-ipfs.
rtrade@capecod:~/stress$ tex-cli client --ea 192.168.1.201:9090 --insecure=true node peer count connected peer count: 746 rtrade@capecod:~/stress$ ipfs swarm peers | wc -l 133
To enable periodic bootstrap you can use
--bootstrap.periodic, --bpp and should you want to configure the interval to something other than the default 2 minutes
--bootstrap.periodic.interval value, --bppi value where
value is a time.Duration value such as
2m0s, 1hr etc…
Note that to use periodic bootstrap, you must also use the regular bootstrapping method enabled with
All non-replication commands that use the gRPC API are grouped under the
client command. Previously you used to be able to configure the client via the yaml configuration file, however this proved to be a bit difficult to use via the CLI and involved shipping copies of the config file to whatever machine you were using the CLI on. This has been refactored to use the following two flags under the
--endpoint.address, --ea- the address of the TemporalX gRPC server
--insecure- indicates whether the endpoint requires TLS encryption or if it is insecure
Your First Upload
To upload a file located at
/tmp/foo.txt as a unixfs object to your local node, and make it publicly available to the IPFS network run the command:
$ tex-cli client --ea localhost:9090 file upload --file.name /tmp/foo.txt
Which will return output like:
$ tex-cli client --ea localhost:9090 file upload --file.name /tmp/foo.txt hash of file bafybeifxokjh6pny5eq7fdh3bhik4sfzrpmevp5c24guonwtu44iusa5h4
To download the file and save it at
/tmp/foo2.txt run the command
$ tex-cli client --ea localhost:9090 file download --cid bafybeifxokjh6pny5eq7fdh3bhik4sfzrpmevp5c24guonwtu44iusa5h4 --save.path /tmp/foo2.txt
When you run the
client file upload command, you end up storing the given file as a unixfs object, and you announce to the network that you are providing the returned hash. When you run the
client file download command, we first check if node has the data for the given cid locally, and if not we ask the rest of the network for that data.
No output isn’t a sign of anything going wrong, and means your action completed. For example
client file download and
client file upload by default dont give any output. If you want to display some additional information, try the flag
Using the configuration file you can enable metric collection that gets exposed via a prometheus http endpoint. You can either consume from this endpoint directly, or plug it into tools like Grafana for nice looking charts.
Within the config file set
prometheus.enabled: true and provide an ip+port you want to expose the metrics on. The metrics will be available on the path
/metrics. For example if you provided the ip+port
127.0.0.1:9093 you can go to
127.0.0.1:9093/metrics and start collecting your data.
Additionally you can enable system profiling in the same way, however the path for that information is
The following usage of
--seed.metrics will enable seeding of prometheus metrics:
$> tex-cli server --seed.metrics (long form) $> tex-cli server --sm (short form)
localhost:9999 we have an admin gRPC API that allows low-level management of TemporalX, in particular it allows managed the garbage collection of the reference counted blockstore.
By default, logs are printed to standard out, and also stored on disk where ever you specify by the
log_file config file key. By default we display, and log all levels except debug.
There are a few environment variables that can be used to adjust logging:
DEV_LOGGING=true- enables logging of extra processing information useful when developing on TemporalX.
DEBUG_LOGGING=true- enables collection of debug level information.
FILE_LOGGING=true- disables logging of information to standard out, and only logs to the log file.
Additionally some of the libraries we use such as
go-libp2p have internal logging systems. To enable those, you can use the environment variable name
IPFS_LOGGING, and set it to a log level. For example
IPFS_LOGGING=debug will enable debug level log collection from libraries use