---
layout: docs
page_title: Server Install
description: |-
  The recommended way to install the server is using the waypoint install command. This command will install a server into Docker, Kubernetes, AWS ECS, or Nomad, bootstrap the server, and configure your local CLI to access that server. It is a single command to get up and running with Waypoint.
---

# Waypoint Server Install

The recommended way to install the server is using the
[`waypoint install`](/commands/install) command.
This command will install a server into Docker, Kubernetes, AWS ECS, or Nomad,
bootstrap the server, and configure your local CLI to access that server.
It is a single command to get up and running with Waypoint.

This command is configured to install recommended defaults out of the box, while
giving enough dials and options for users to tweak to still be useful. If there's
a specific setup that doesn't work for you with `waypoint install`, we recommend
looking at the [server run](/docs/server/run) documentation instead or opening
an issue on GitHub and requesting a feature enhancement.

## Officially Supported Server Platforms

Currently, Waypoint supports running its server on the following platforms:

- [Kubernetes](/docs/server/install#kubernetes-platform)
- [Nomad](/docs/server/install#nomad-platform)
- [Amazon ECS](/docs/server/install#aws-ecs-platform)
- [Docker](/docs/server/install#docker-platform)

### Kubernetes Platform

Installing Waypoint server onto Kubernetes has a couple of options: Using the
waypoint-helm chart or using `waypoint install`.

The officially supported [hashicorp/waypoint-helm](https://github.com/hashicorp/waypoint-helm)
chart can be used to deploy Waypoint server directly onto a Kubernetes cluster with Helm charts.
We recommend reading the README detailed on that project for more information on
how to get going using Helm and Waypoint.

You can also install Waypoint server onto Kubernetes using the `waypoint install`
command. This command sets up a Service, Statefulset, Deployment, and Replicaset
and deploys Waypoint server and its runner as two separate pods by default.

### Nomad Platform

To install Waypoint server on Nomad, there are a few requirements that should be
met prior to running the install:

You must use a CSI or Host volume to store Waypoint server's database. A host volume
or CSI volume provider can be specified as a command line option to `waypoint install` and
should be registered in Nomad prior to running the `waypoint install` command.

This command sets up a Nomad job for running Waypoint server and its
runner as two separate jobs by default.

~> **NOTE**: **We strongly recommend using Consul** for networking support in Nomad running Waypoint server.

By default, the CLI installer will automatically create a service for Consul in
Nomad for running Waypoint server. This is an important default, as it gives
Waypoint server a stable hostname for your clients to point at, or remote
runners to use for calling back to the Waypoint server. There are a handful of
installer flags that let you configure what tags the Waypoint server and UI
service should have, what datacenter or domain Consul is in, or
define your own Consul service hostname to use. By default, the
`waypoint install` helper will return a hostname crafted using the default
expected host for a Consul service, i.e. `waypoint-server.service.dc1.consul`.

When running the install helper, the CLI should show the Consul DNS backed hostname of Waypoint
server at the end of an install:

```shell-session
$ waypoint install -platform=nomad -accept-tos -nomad-host-volume="waypoint"
✓ Waypoint server ready
✓ The CLI has been configured to automatically install a Consul service for
the Waypoint service backend and ui service in Nomad.
✓ Server installed and configured!
✓ Successfully connected to Waypoint server in Nomad!
✓ Installing runner...
✓ Waypoint runner installed
Waypoint server successfully installed and configured!

The CLI has been configured to connect to the server automatically. This
connection information is saved in the CLI context named "install-1635801894".
Use the "waypoint context" CLI to manage CLI contexts.

The server has been configured to advertise the following address for
entrypoint communications. This must be a reachable address for all your
deployments. If this is incorrect, manually set it using the CLI command
"waypoint server config-set".

To launch and authenticate into the Web UI, run:
waypoint ui -authenticate

Advertise Address: waypoint-server.service.dc1.consul:9701
Web UI Address: https://waypoint-ui.service.dc1.consul:9702
```

Notice that the advertise and web ui address is shown as a hostname, rather than an IP.

Without using Consul, if the Waypoint server allocation ever gets restarted in Nomad, the IP
address will no longer be valid, and you will have to upgrade every server client's context.
There are ways around this issue that are considered more advanced, and are likely
better candidates for using the [server run](/docs/server/run) flow for setting
up Waypoint server.

If you do not wish to automatically register a Consul service in Nomad for
Waypoint server by default with `waypoint install`, it can always be disabled
by including the `-nomad-consul-service=false` flag. You should then see
an IP address from the Nomad allocation after the Waypoint install helper finishes.

### AWS ECS Platform

Waypoint supports installing the server in AWS ECS. Several AWS resources are created
as part of the install. The default cluster name is `waypoint-server`; this can
be changed by specifying the value for the flag `-ecs-cluster`. The resources
are tagged with `waypoint-server` as the tag name; this is not able to be changed
as Waypoint needs a way to track all the resources that are part of the server install.

The main components installed are:

- EFS Filesystem: used for persisting the Waypoint server database
- EC2 Security Group: authorizing traffic in to the cluster, as well as enabling access to the EFS FileSystem from the Cluster
- CloudWatch Log Groups: a log group is created for each of the Waypoint server and runner services
- IAM Execution role
- Network load balancer: required to enable both HTTP and gRPC connections (see `NOTE`)
- Load balancing target groups: a target group is created for each of the Waypoint server and runner services
- ECS Cluster: a cluster dedicated to running the Waypoint server and runner
- ECS server service: runs the Waypoint server task
- ECS runner service: runs the default Waypoint runner task
- ECS Task Definitions: for both the server and runner

~> **NOTE**: A Network Load Balancer is required because user-supplied TLS certificates are not yet supported.

An example ECS install should result in output similar to the below:

```shell-session
$ waypoint install -platform=ecs -accept-tos
✓ Networking setup
✓ Created new ECS cluster: waypoint-server
✓ EFS ready
✓ Found existing IAM role to use: waypoint-server-execution-role
✓ Created CloudWatchLogs group to store logs in: waypoint-server-logs
✓ Network load balancer created
✓ Created ECS Service (waypoint, cluster-name: waypoint-server)
✓ Waiting for target group to be healthy...
✓ Service launched!
✓ Server installed and configured!
✓ Successfully connected to Waypoint server in ECS!
✓ Installing runner...
✓ Registered ondemand runner!
✓ Found existing IAM role to use: waypoint-server-execution-role
✓ Found existing IAM role to use: waypoint-runner
✓ Created CloudWatchLogs group to store logs in: waypoint-runner-logs
✓ Runner service created
Waypoint server successfully installed and configured!

The CLI has been configured to connect to the server automatically. This
connection information is saved in the CLI context named "install-1656552433".
Use the "waypoint context" CLI to manage CLI contexts.

The server has been configured to advertise the following address for
entrypoint communications. This must be a reachable address for all your
deployments. If this is incorrect, manually set it using the CLI command
"waypoint server config-set".

To launch and authenticate into the Web UI, run:
waypoint ui -authenticate

Advertise Address: waypoint-server-nlb-xyz123.elb.us-west-2.amazonaws.com:9701
Web UI Address: https://waypoint-server-nlb-xyz123.elb.us-west-2.amazonaws.com:9702
```

### Docker Platform

Waypoint supports running the Waypoint server directly in Docker. Generally, this flow
is recommended only for development to get started using Waypoint. We do not
recommend using Waypoint running in Docker for production workflows.

This command sets up Docker containers for running Waypoint server and its
runner as two separate containers by default.
