Server Maintenance
Warning
This content is part of the legacy version of Waypoint that is no longer actively maintained. For additional information on the new vision of Waypoint, check out this blog post and the HCP Waypoint documentation.
A Waypoint server needs to be maintained to ensure smooth operation and to protect against unexpected events such as server crashes. This page outlines various maintenance-related topics for smooth operation of a Waypoint server.
Logs
Server logs are output to stderr.
For waypoint install-based servers, logs are always very verbose (-vvv).
For manually run servers, you can control log level using multiple -v flags
or by setting WAYPOINT_LOG_LEVEL to one of "trace", "debug", "info", "warn",
or "error".
Database
The Waypoint server stores data into a single data.db file.
Path to Database
For waypoint install-based servers:
- Docker -
/data/data.db - ECS -
/waypoint-data/data.db - Kubernetes -
/data/data.db - Nomad -
/alloc/data.db
For manually run servers, it is dependent on the value of the -db flag.
Backup / Restore
The Waypoint server supports both an online and offline backup and restore.
Online Backup and Restore
To backup the database, use the waypoint server snapshot
command. This command will take an online snapshot of the database and
write it to a local gzip-compressed file. In the example below, we take
a snapshot and save it as a backup.snap:
Warning! The snapshot data contains secret and sensitive information (such as auth tokens) unencrypted. Snapshots are highly sensitive and should be carefully protected.
You can then restore this snapshot using waypoint server restore.
This command stages the restore but does not activate the restore. This means
that the old data (prior to the restore) will continue to be the live data
until the restore is activated. To activate the restore, you must restart the server. You may call restore
multiple times to stage different backups; each call will overwrite the last
staged restore.
If you are running the Waypoint server in an environment that will automatically
restart it for you (such as Kubernetes or Nomad), then you may pass the
-exit flag to waypoint server restore. This will cause the Waypoint server
to abruptly exit after staging the restore. This expects that the underlying
platform will restart the process after noticing it has died.
Offline Restore with a Snapshot
You can restore a server with a snapshot taken when the server was online
via waypoint server snapshot.
In the server data directory (where the data.db file would normally be),
copy the snapshot data and name the file waypoint-restore.db. For example,
if you normally run the Waypoint server as waypoint server -db=/data/data.db
then you should copy the snapshot data to /data/waypoint-restore.db.
The real database doesn't need to exist; the restore process also works with
new, fresh servers. However, the snapshot data must still be named waypoint-restore.db.
Start or restart the server. On boot, it will notice the existence of a restore snapshot and attempt to restore. The logs should contain information about the restore. If the restore fails, the server will not start.
Snapshot Version Compatibility
Online snapshots are safe to restore against any version of Waypoint.
If a snapshot is incompatible, an error will be shown on start and no existing data will be corrupted. We intend for snapshots to remain compatible with all future versions of Waypoint. If there are any exceptions, it'll be noted in the upgrade guide. Please always read the upgrade guide for all versions leading up to the version you're installing.
Offline Backup
In an emergency, you may perform an offline backup by copying the database file directly. In this case, you may restore the backup offline by replacing the database file.
This method of backup is not recommended. The raw database file compatibility is not guaranteed across versions. It is highly recommended you perform online snapshots with online or offline restores using that snapshot data.