diff --git a/docs/guides/cloud/cli.rst b/docs/guides/cloud/cli.rst new file mode 100644 index 00000000000..805ba0c980c --- /dev/null +++ b/docs/guides/cloud/cli.rst @@ -0,0 +1,60 @@ +.. _ref_guide_cloud_cli: + +=== +CLI +=== + +:edb-alt-title: Using EdgeDB Cloud via the CLI + +To use EdgeDB Cloud via the CLI, first log in using +:ref:`ref_cli_edgedb_cloud_login`. Once your login is successful, you will be +able to create an instance using either :ref:`ref_cli_edgedb_instance_create` +or :ref:`ref_cli_edgedb_project_init`, depending on whether you also want to +create a local project linked to your instance. + +* :ref:`ref_cli_edgedb_instance_create` with an instance name of + ``/``. + + .. code-block:: bash + + $ edgedb instance create / + +* :ref:`ref_cli_edgedb_project_init` with the ``--server-instance`` option. Set + the server instance name to ``/``. + + .. code-block:: bash + + $ edgedb project init \ + --server-instance / + + Alternatively, you can run ``edgedb project init`` *without* the + ``--server-instance`` option and enter an instance name in the + ``/`` format when prompted interactively. + +.. note:: + + Please be aware of the following restrictions on EdgeDB Cloud instance + names: + + * can contain only Latin alpha-numeric characters or ``-`` + * cannot start with a dash (``-``) or contain double dashes (``--``) + * maximum instance name length is 61 characters minus the length of your + organization name (i.e., length of organization name + length of instance + name must be fewer than 62 characters) + +To use ``edgedb instance create``: + +.. code-block:: bash + + $ edgedb instance create / + +To use ``edgedb project init``: + +.. code-block:: bash + + $ edgedb project init \ + --server-instance / + +Alternatively, you can run ``edgedb project init`` *without* the +``--server-instance`` option and enter an instance name in the +``/`` format when prompted interactively. diff --git a/docs/guides/cloud/deploy/images/cloud-netlify-config.png b/docs/guides/cloud/deploy/images/cloud-netlify-config.png new file mode 100644 index 00000000000..bb6ec9f08bd Binary files /dev/null and b/docs/guides/cloud/deploy/images/cloud-netlify-config.png differ diff --git a/docs/guides/cloud/deploy/images/cloud-vercel-config.png b/docs/guides/cloud/deploy/images/cloud-vercel-config.png new file mode 100644 index 00000000000..de389d522b2 Binary files /dev/null and b/docs/guides/cloud/deploy/images/cloud-vercel-config.png differ diff --git a/docs/guides/cloud/deploy/index.rst b/docs/guides/cloud/deploy/index.rst new file mode 100644 index 00000000000..db6966fd06a --- /dev/null +++ b/docs/guides/cloud/deploy/index.rst @@ -0,0 +1,25 @@ +.. _ref_guide_cloud_deploy: + +============= +Deploy an app +============= + +:edb-alt-title: Deploying applications built on EdgeDB Cloud + +For your production deployment, generate a dedicated secret key for your +instance with :ref:`ref_cli_edgedb_cloud_secretkey_create` or via the web UI's +"Secret Keys" pane in your instance dashboard. Create two environment variables +accessible to your production application: + +* ``EDGEDB_SECRET_KEY``- contains the secret key you generated +* ``EDGEDB_INSTANCE``- the name of your EdgeDB Cloud instance + (``/``) + +If you use one of these platforms, try the platform's guide for +platform-specific instructions: + +.. toctree:: + :maxdepth: 1 + + vercel + netlify diff --git a/docs/guides/cloud/deploy/netlify.rst b/docs/guides/cloud/deploy/netlify.rst new file mode 100644 index 00000000000..1fd60c172ee --- /dev/null +++ b/docs/guides/cloud/deploy/netlify.rst @@ -0,0 +1,36 @@ +.. _ref_guide_cloud_deploy_netlify: + +======================== +Deploy an app on Netlify +======================== + +:edb-alt-title: Deploying applications built on EdgeDB Cloud to Netlify + +.. note:: + + This guide assumes the Git deployment method on Netlify, but you may also + deploy your site using other methods. Just make sure the EdgeDB Cloud + environment variables are set, and your app should have connectivity to + your instance. + +1. Push project to GitHub or some other Git remote repository +2. Create and make note of a secret key for your EdgeDB Cloud instance +3. On your Netlify Team Overview view under Sites, click Import from Git +4. Import your project's repository +5. Configure the build settings appropriately for your app +6. Click the Add environment variable button +7. Use the New variable button to add two variables: + + - ``EDGEDB_INSTANCE`` containing your EdgeDB Cloud instance name (in + ``/`` format) + - ``EDGEDB_SECRET_KEY`` containing the secret key you created and noted + previously. + +8. Click Deploy + +.. image:: images/cloud-netlify-config.png + :width: 100% + :alt: A screenshot of the Netlify deployment configuration view + highlighting the environment variables section where a user will + need to set the necessary variables for EdgeDB Cloud instance + connection. diff --git a/docs/guides/cloud/deploy/vercel.rst b/docs/guides/cloud/deploy/vercel.rst new file mode 100644 index 00000000000..f8204eee715 --- /dev/null +++ b/docs/guides/cloud/deploy/vercel.rst @@ -0,0 +1,26 @@ +.. _ref_guide_cloud_deploy_vercel: + +======================= +Deploy an app on Vercel +======================= + +:edb-alt-title: Deploying applications built on EdgeDB Cloud to Vercel + +1. Push project to GitHub or some other Git remote repository +2. Create and make note of a secret key for your EdgeDB Cloud instance +3. From Vercel's Overview tab, click Add New > Project +4. Import your project's repository +5. In "Configure Project," expand "Environment Variables" to add two variables: + + - ``EDGEDB_INSTANCE`` containing your EdgeDB Cloud instance name (in + ``/`` format) + - ``EDGEDB_SECRET_KEY`` containing the secret key you created and noted + previously. + +6. Click Deploy + +.. image:: images/cloud-vercel-config.png + :width: 100% + :alt: A screenshot of the Vercel deployment configuration view highlighting + the environment variables section where a user will need to set the + necessary variables for EdgeDB Cloud instance connection. diff --git a/docs/guides/cloud/index.rst b/docs/guides/cloud/index.rst index bc6bf1ce04d..21ec06c8358 100644 --- a/docs/guides/cloud/index.rst +++ b/docs/guides/cloud/index.rst @@ -13,135 +13,15 @@ interface nearly identical to the :ref:`EdgeDB UI `. .. edb:youtube-embed:: IG1MggUzzH4 -CLI Cloud Interface -=================== - -To use Cloud via the CLI, first log in using :ref:`ref_cli_edgedb_cloud_login`. -Once your login is successful, you will be able to create an instance using -either :ref:`ref_cli_edgedb_instance_create` or -:ref:`ref_cli_edgedb_project_init`, depending on whether you also want to -create a local project linked to your instance. - -* :ref:`ref_cli_edgedb_instance_create` with an instance name of - ``/``. - - .. code-block:: bash - - $ edgedb instance create / - -* :ref:`ref_cli_edgedb_project_init` with the ``--server-instance`` option. Set - the server instance name to ``/``. - - .. code-block:: bash - - $ edgedb project init \ - --server-instance / - - Alternatively, you can run ``edgedb project init`` *without* the - ``--server-instance`` option and enter an instance name in the - ``/`` format when prompted interactively. - -.. note:: - - Please be aware of the following restrictions on EdgeDB Cloud instance - names: - - * can contain only Latin alpha-numeric characters or ``-`` - * cannot start with a dash (``-``) or contain double dashes (``--``) - * maximum instance name length is 61 characters minus the length of your - organization name (i.e., length of organization name + length of instance - name must be fewer than 62 characters) - -To use ``edgedb instance create``: - -.. code-block:: bash - - $ edgedb instance create / - -To use ``edgedb project init``: - -.. code-block:: bash - - $ edgedb project init \ - --server-instance / - -Alternatively, you can run ``edgedb project init`` *without* the -``--server-instance`` option and enter an instance name in the -``/`` format when prompted interactively. - - -Web Cloud Interface -=================== - -If you'd prefer, you can also manage your account via `the EdgeDB Cloud -web-based GUI `_. - -The first time you access the web UI, you will be prompted to log in. Once you -log in with your account, you'll be on the "Instances" tab of the front page -which shows your instance list. The other two tabs allow you to manage your -organization settings and billing. - -Instances ---------- - -If this is your first time accessing EdgeDB Cloud, this list will be empty. To -create an instance, click "Create new instance." This will pop up a modal -allowing you to name your instance and specify the version of EdgeDB and the -region for the instance. - -Once the instance has been created, you'll see the instance dashboard which -allows you to monitor your instance, navigate to the management page for its -databases, and create secret keys. - -You'll also see instructions in the bottom-right for linking your EdgeDB CLI to -your EdgeDB Cloud account. You do this by running the CLI command ``edgedb -cloud login``. This will make all of your EdgeDB Cloud instances accessible via -the CLI. You can manage them just as you would other remote EdgeDB instances. - -If you want to manage a database inside your instance, click through on -its name from the top right of the instance dashboard. If you just created -a database, the database management view will be mostly empty except for a -button offering to create a sample database. Once you have a schema created -and some data in a database, this view will offer you similar tools to those -in our local UI. - -You'll be able to access a REPL, edit complex queries or build them -graphically, inspect your schema, and browse your data. - -Org Settings ------------- - -This tab allows you to add GitHub organizations for which you are an admin. -If you don't see your organization's name here, you may need to update your -`org settings`_ in GitHub to allow EdgeDB Cloud to read your list of -organizations, and then refresh the org list. - -.. lint-off - -.. _org setings: - https://docs.github.com/en/organizations/managing-oauth-access-to-your-organizations-data/approving-oauth-apps-for-your-organization - -.. lint-on - -Billing -------- - -On this page you can manage your account type and payment methods, and set your -email for receiving billing info. Optionally, you can also save your payment -info using `Link `_, `Stripe's `_ -fast-checkout solution. - -Deploying your application -========================== - -For your production deployment, generate a dedicated secret key for your -instance with :ref:`ref_cli_edgedb_cloud_secretkey_create` or via the web UI's -"Secret Keys" pane in your instance dashboard. Create two environment variables -accessible to your production application: - -* ``EDGEDB_SECRET_KEY``- contains the secret key you generated -* ``EDGEDB_INSTANCE``- the name of your EdgeDB Cloud instance - (``/``) +.. toctree:: + :maxdepth: 2 + :hidden: + + cli + web + deploy/index + deploy/vercel + deploy/netlify Questions? Problems? Bugs? diff --git a/docs/guides/cloud/web.rst b/docs/guides/cloud/web.rst new file mode 100644 index 00000000000..2aef68061a3 --- /dev/null +++ b/docs/guides/cloud/web.rst @@ -0,0 +1,65 @@ +.. _ref_guide_cloud_web: + +======= +Web GUI +======= + +:edb-alt-title: Using EdgeDB Cloud via the web GUI + +If you'd prefer, you can also manage your account via `the EdgeDB Cloud +web-based GUI `_. + +The first time you access the web UI, you will be prompted to log in. Once you +log in with your account, you'll be on the "Instances" tab of the front page +which shows your instance list. The other two tabs allow you to manage your +organization settings and billing. + +Instances +--------- + +If this is your first time accessing EdgeDB Cloud, this list will be empty. To +create an instance, click "Create new instance." This will pop up a modal +allowing you to name your instance and specify the version of EdgeDB and the +region for the instance. + +Once the instance has been created, you'll see the instance dashboard which +allows you to monitor your instance, navigate to the management page for its +databases, and create secret keys. + +You'll also see instructions in the bottom-right for linking your EdgeDB CLI to +your EdgeDB Cloud account. You do this by running the CLI command ``edgedb +cloud login``. This will make all of your EdgeDB Cloud instances accessible via +the CLI. You can manage them just as you would other remote EdgeDB instances. + +If you want to manage a database inside your instance, click through on +its name from the top right of the instance dashboard. If you just created +a database, the database management view will be mostly empty except for a +button offering to create a sample database. Once you have a schema created +and some data in a database, this view will offer you similar tools to those +in our local UI. + +You'll be able to access a REPL, edit complex queries or build them +graphically, inspect your schema, and browse your data. + +Org Settings +------------ + +This tab allows you to add GitHub organizations for which you are an admin. +If you don't see your organization's name here, you may need to update your +`org settings`_ in GitHub to allow EdgeDB Cloud to read your list of +organizations, and then refresh the org list. + +.. lint-off + +.. _org setings: + https://docs.github.com/en/organizations/managing-oauth-access-to-your-organizations-data/approving-oauth-apps-for-your-organization + +.. lint-on + +Billing +------- + +On this page you can manage your account type and payment methods, and set your +email for receiving billing info. Optionally, you can also save your payment +info using `Link `_, `Stripe's `_ +fast-checkout solution. diff --git a/docs/guides/index.rst b/docs/guides/index.rst index 1dc27b2d920..8472375d950 100644 --- a/docs/guides/index.rst +++ b/docs/guides/index.rst @@ -17,7 +17,7 @@ guide! .. toctree:: :maxdepth: 1 - cloud + cloud/index cheatsheet/index deployment/index datamigrations/index