Overview

Prisma APIs are hosted on Prisma servers. These servers provide the runtime environment for Prisma APIs.

Note: Prior to Prisma 1.7, Prisma servers have been called clusters.

In essence, there are three kinds of servers you can deploy your Prisma API to:

Local / self-hosted (using Docker): You can spin up your own Prisma server locally or host them using a cloud provider of your choice. They are managed with the Docker CLI which governs the underlying Docker images and containers for you. Follow this tutorial to learn how to host your own Prisma server on Digital Ocean.
Prisma Sandbox (Prisma Cloud): Prisma Cloud offers free development severs which you can use for learning and prototyping, these servers are called Prisma Sandbox. Note that when deployed to a Prisma Sandbox, your APIs will be rate limited and have an upper bound in storage capacity (see the info box below for further info).
Private servers (Prisma Cloud): A private server is connected to your own database which you're provisioning when initially setting up the server.

For production use cases, private and self-hosted Prisma servers are the preferred option to deploy Prisma services. This chapter is about self-hosted servers, you can learn more about Prisma Cloud here.

Prisma sandboxes are rate limited:

10 requests per 10 seconds (on average)
If this rate is exceeded, requests are being queued in memory. If this queue exceeds 25 requests, an error is returned immediately.
The header field throttled-by is included in HTTP responses. It indicates how long the request was delayed due to throttling (in milli seconds).

The upper bound in storage capacity for a Prisma API that's running in a Sandbox is 100 MB.

</InfoBox>

When you're running prisma deploy for a Prisma API, there are two scenarios with respect to the targeted Prisma server:

The endpoint property in prisma.yml is specified. In this case, the CLI will directly deploy the API to that endpoint.
The endpoint property in prisma.yml is not specified. In this case, the Prisma CLI wizard will prompt you with a few questions, construct the endpoint for you and deploy the API to the corresponding server. It also writes the endpoint into prisma.yml, this will be used as the default for future deploys. To bring up the wizard again, you can run prisma deploy --new or remove the endpoint manually from prisma.yml.

Authentication

Docker

Prisma servers support symmetric as well as asymmetric authentication approaches.

Asymmetric authentication using public/private key pairs

Using the asymmetric authentication approach, Prisma servers are secured using public/private key pairs.

The Prisma servers knows the public key (via the legacySecret property in docker-compose.yml, see here for more info). The private key is known locally by the Prisma CLI and used to generate authentication tokens. These tokens are used to authenticate requests against the Prisma server (e.g. an invocation of prisma deploy) which can then be validated by the Prisma server using its public key.

Symmetric approach using a single secret

In Prisma 1.7, a new authentication approach for Prisma servers has been introduced. It uses a single secret to authenticate requests made by the Prisma CLI against a Prisma server.

The secret can be chosen by the admin of the Prisma server. It is set via the managementApiSecret property in the docker-compose.yml which is used to deploy the Prisma server. If not specified, the CLI doesn't need to authenticate its requests. If specified, the CLI needs to have access to an environment variable called PRISMA_MANAGEMENT_API_SECRET which contains the secret, otherwise the CLI can not talk to the Prisma server (e.g. prisma deploy will fail).

Prisma Cloud

Login

The CLI authenticates against Prisma Cloud using the cloudSessionKey stored in ~/.prisma/config.yml. The CLI writes that key into that file upon the initial login: prisma login.

Logout

To logout from the Prisma CLI remove the cloudSessionKey from ~/.prisma/config.yml file.