.. _ref_guide_deployment_digitalocean:

============
DigitalOcean
============

:edb-alt-title: Deploying EdgeDB to DigitalOcean

In this guide we show how to deploy EdgeDB to DigitalOcean either with a
One-click Deploy option or a
:ref:`managed PostgreSQL <ref_guide_deployment_digitalocean_managed>`
database as the backend.

One-click Deploy
++++++++++++++++

Prerequisites
=============

* ``edgedb`` CLI (`install <edgedb-install_>`_)
* DigitalOcean account

Click the button below and follow the droplet creation workflow on
DigitalOcean to deploy an EdgeDB instance.

.. image:: https://www.deploytodo.com/do-btn-blue.svg
   :target: 1-click-button_
   :width: 225px

.. _1-click-button:
   https://marketplace.digitalocean.com/apps/edgedb?refcode=f0b0d77b5d49

By default, the admin password is ``edgedbpassword``; let's change that to
something more secure. First, find your droplet's IP address on the
`DigitalOcean dashboard <https://cloud.digitalocean.com/droplets>`_ and assign
it to an environment variable ``IP``.

.. _DigitalOcean: https://cloud.digitalocean.com/droplets?
.. _here: edgedb-install_

.. code-block:: bash

   $ IP=<your-droplet-ip>

Then use the ``read`` command to securely assign a value to the ``PASSWORD``
environment variable.

.. code-block:: bash

   $ echo -n "> " && read -s PASSWORD

Use these variables to change the password for the default role ``edgedb``.

.. code-block:: bash

   $ printf edgedbpassword | edgedb query \
         --host $IP \
         --password-from-stdin \
         --tls-security insecure \
         "alter role edgedb set password := '${PASSWORD}'"
   OK: ALTER ROLE

.. _ref_guide_deployment_digitalocean_link:

Construct the DSN
-----------------

Let's construct your instance's DSN (also known as a "connection string").
We'll write the value to a file called ``dsn.txt`` so it doesn't get stored in
shell logs.

.. code-block:: bash

   $ echo edgedb://edgedb:$PASSWORD@$IP > dsn.txt

Copy the value from ``dsn.txt``. Run the following command to open a REPL
to the new instance.

..  code-block:: bash

   $ edgedb --dsn <dsn> --tls-security insecure
   edgedb>

Success! You're now connected to your remote instance.

It's often useful to assign an alias to the remote instance using ``edgedb
instance link``.

.. code-block:: bash

   $ edgedb instance link \
       --dsn <dsn> \
       --trust-tls-cert \
       --non-interactive \
       my_instance
   Authenticating to edgedb://edgedb@1.2.3.4:5656/edgedb
   Trusting unknown server certificate:
   SHA1:1880da9527be464e2cad3bdb20dfc430a6af5727
   Successfully linked to remote instance. To connect run:
     edgedb -I my_instance

You can now use the ``-I`` CLI flag to execute commands against your remote
instance:

.. code-block:: bash

   $ edgedb -I my_instance
   edgedb>


.. _ref_guide_deployment_digitalocean_managed:

Deploy with Managed PostgreSQL
++++++++++++++++++++++++++++++

Prerequisites
=============

* ``edgedb`` CLI (`install <edgedb-install_>`_)
* DigitalOcean account
* ``doctl`` CLI (`install <doclt-install_>`_)
* ``jq`` (`install <jq_>`_)

.. _edgedb-install: https://www.edgedb.com/install
.. _doclt-install: https://docs.digitalocean.com/reference/doctl/how-to/install
.. _jq: https://stedolan.github.io/jq/


Create a managed PostgreSQL instance
====================================

If you already have a PostgreSQL instance you can skip this step.

.. code-block:: bash

   $ DSN="$( \
         doctl databases create edgedb-postgres \
             --engine pg \
             --version 14 \
             --size db-s-1vcpu-1gb \
             --num-nodes 1 \
             --region sfo3 \
             --output json \
         | jq -r '.[0].connection.uri' )"


Provision a droplet
===================

Replace ``$SSH_KEY_IDS`` with the ids for the ssh keys you want to ssh into the
new droplet with. Separate multiple values with a comma. You can list your
keys with ``doctl compute ssh-key list``.  If you don't have any ssh keys in
your DigitalOcean account you can follow `this guide <upload-ssh-keys_>`_ to
add one now.

.. _upload-ssh-keys:
   https://docs.digitalocean.com/products/droplets
   /how-to/add-ssh-keys/to-account/

.. code-block:: bash

   $ IP="$( \
         doctl compute droplet create edgedb \
             --image edgedb \
             --region sfo3 \
             --size s-2vcpu-4gb \
             --ssh-keys $SSH_KEY_IDS \
             --format PublicIPv4 \
             --no-header \
             --wait )"

Configure the backend Postgres DSN. To simplify the initial deployment, let's
instruct EdgeDB to run in insecure mode (with password authentication off and
an autogenerated TLS certificate). We will secure the instance once things are
up and running.

.. code-block:: bash

   $ printf "EDGEDB_SERVER_BACKEND_DSN=${DSN} \
   \nEDGEDB_SERVER_SECURITY=insecure_dev_mode\n" \
   | ssh root@$IP -T "cat > /etc/edgedb/env"

   $ ssh root@$IP "systemctl restart edgedb.service"

Set the superuser password.

.. code-block:: bash

   $ echo -n "> " && read -s PASSWORD

   $ edgedb -H $IP --tls-security insecure query \
         "alter role edgedb set password := '$PASSWORD'"
   OK: ALTER ROLE

Set the security policy to strict.

.. code-block:: bash

   $ printf "EDGEDB_SERVER_BACKEND_DSN=${DSN} \
   \nEDGEDB_SERVER_SECURITY=strict\n" \
   | ssh root@$IP -T "cat > /etc/edgedb/env"

   $ ssh root@$IP "systemctl restart edgedb.service"


.. note::

   To upgrade an existing EdgeDB droplet to the latest point release, ``ssh``
   into your droplet and run the following.

   .. code-block:: bash

      $ apt-get update && apt-get install --only-upgrade edgedb-server-3
      $ systemctl restart edgedb

That's it! Refer to the :ref:`Construct the DSN
<ref_guide_deployment_digitalocean_link>` section above to connect to your
instance.

.. note::

   The command groups ``edgedb instance`` and ``edgedb project`` are not
   intended to manage production instances.

Health Checks
=============

Using an HTTP client, you can perform health checks to monitor the status of
your EdgeDB instance. Learn how to use them with our :ref:`health checks guide
<ref_guide_deployment_health_checks>`.
