diff --git a/docs/explanations/install.rst b/docs/explanations/install.rst
index df76e8aa5..fad838b60 100644
--- a/docs/explanations/install.rst
+++ b/docs/explanations/install.rst
@@ -261,126 +261,3 @@ You can build PostgREST from source with `Stack <https://github.com/commercialha
    - `--install-ghc` flag is only needed for the first build and can be omitted in the subsequent builds.
 
 * Check that the server is installed: :code:`postgrest --help`.
-
-.. _deploy_heroku:
-
-Deploying to Heroku
-===================
-
-1.  Log into Heroku using the `Heroku CLI <https://devcenter.heroku.com/articles/heroku-cli>`_:
-
-  .. code-block:: bash
-
-    # If you have multiple Heroku accounts, use flag '--interactive' to switch between them
-    heroku login --interactive
-
-
-2.  Create a new Heroku app using the PostgREST buildpack:
-
-  .. code-block:: bash
-
-    mkdir ${YOUR_APP_NAME}
-    cd ${YOUR_APP_NAME}
-    git init .
-
-    heroku apps:create ${YOUR_APP_NAME} --buildpack https://github.com/PostgREST/postgrest-heroku.git
-    heroku git:remote -a ${YOUR_APP_NAME}
-
-3.  Create a new Heroku PostgreSQL add-on attached to the app and keep notes of the assigned add-on name (e.g. :code:`postgresql-curly-58902`) referred later as ${HEROKU_PG_DB_NAME}
-
-  .. code-block:: bash
-
-    heroku addons:create heroku-postgresql:standard-0 -a ${YOUR_APP_NAME}
-    # wait until the add-on is available
-    heroku pg:wait -a ${YOUR_APP_NAME}
-
-4.  Create the necessary user roles according to the
-    `PostgREST documentation <https://postgrest.org/en/stable/auth.html>`_:
-
-  .. code-block:: bash
-
-    heroku pg:credentials:create --name api_user -a ${YOUR_APP_NAME}
-    # use the following command to ensure the new credential state is active before attaching it
-    heroku pg:credentials -a ${YOUR_APP_NAME}
-
-    heroku addons:attach ${HEROKU_PG_DB_NAME} --credential api_user -a ${YOUR_APP_NAME}
-
-5.  Connect to the PostgreSQL database and create some sample data:
-
-  .. code-block:: bash
-
-    heroku psql -a ${YOUR_APP_NAME}
-
-  .. code-block:: postgres
-
-    # from the psql command prompt execute the following commands:
-    create schema api;
-
-    create table api.todos (
-    id serial primary key,
-    done boolean not null default false,
-    task text not null,
-    due timestamptz
-    );
-
-    insert into api.todos (task) values
-    ('finish tutorial 0'), ('pat self on back');
-
-    grant usage on schema api to api_user;
-    grant select on api.todos to api_user;
-
-6.  Create the :code:`Procfile`:
-
-  .. code-block:: bash
-
-    web: PGRST_SERVER_HOST=0.0.0.0 PGRST_SERVER_PORT=${PORT} PGRST_DB_URI=${PGRST_DB_URI:-${DATABASE_URL}} ./postgrest-${POSTGREST_VER}
-  ..
-
-  Set the following environment variables on Heroku:
-
-  .. code-block:: bash
-
-    heroku config:set POSTGREST_VER=10.0.0
-    heroku config:set PGRST_DB_SCHEMA=api
-    heroku config:set PGRST_DB_ANON_ROLE=api_user
-  ..
-
-  PGRST_DB_URI can be set if an external database is used or if it's different from the default Heroku DATABASE_URL. This latter is used if nothing is provided.
-  POSTGREST_VER is mandatory to select and build the required PostgREST release.
-
-  See https://postgrest.org/en/stable/configuration.html#environment-variables for the full list of environment variables.
-
-7.  Build and deploy your app:
-
-  .. code-block:: bash
-
-    git add Procfile
-    git commit -m "PostgREST on Heroku"
-    git push heroku master
-  ..
-
-  Your Heroku app should be live at :code:`${YOUR_APP_NAME}.herokuapp.com`
-
-8.  Test your app
-
-    From a terminal display the application logs:
-
-  .. code-block:: bash
-
-    heroku logs -t
-  ..
-
-  From a different terminal retrieve with curl the records previously created:
-
-  .. code-block:: bash
-
-    curl https://${YOUR_APP_NAME}.herokuapp.com/todos
-  ..
-
-  and test that any attempt to modify the table via a read-only user is not allowed:
-
-  .. code-block:: bash
-
-    curl https://${YOUR_APP_NAME}.herokuapp.com/todos -X POST \
-     -H "Content-Type: application/json" \
-     -d '{"task": "do bad thing"}'
diff --git a/docs/integrations/heroku.rst b/docs/integrations/heroku.rst
new file mode 100644
index 000000000..614950c1d
--- /dev/null
+++ b/docs/integrations/heroku.rst
@@ -0,0 +1,122 @@
+.. _deploy_heroku:
+
+Heroku
+======
+
+1.  Log into Heroku using the `Heroku CLI <https://devcenter.heroku.com/articles/heroku-cli>`_:
+
+  .. code-block:: bash
+
+    # If you have multiple Heroku accounts, use flag '--interactive' to switch between them
+    heroku login --interactive
+
+
+2.  Create a new Heroku app using the PostgREST buildpack:
+
+  .. code-block:: bash
+
+    mkdir ${YOUR_APP_NAME}
+    cd ${YOUR_APP_NAME}
+    git init .
+
+    heroku apps:create ${YOUR_APP_NAME} --buildpack https://github.com/PostgREST/postgrest-heroku.git
+    heroku git:remote -a ${YOUR_APP_NAME}
+
+3.  Create a new Heroku PostgreSQL add-on attached to the app and keep notes of the assigned add-on name (e.g. :code:`postgresql-curly-58902`) referred later as ${HEROKU_PG_DB_NAME}
+
+  .. code-block:: bash
+
+    heroku addons:create heroku-postgresql:standard-0 -a ${YOUR_APP_NAME}
+    # wait until the add-on is available
+    heroku pg:wait -a ${YOUR_APP_NAME}
+
+4.  Create the necessary user roles according to the
+    `PostgREST documentation <https://postgrest.org/en/stable/auth.html>`_:
+
+  .. code-block:: bash
+
+    heroku pg:credentials:create --name api_user -a ${YOUR_APP_NAME}
+    # use the following command to ensure the new credential state is active before attaching it
+    heroku pg:credentials -a ${YOUR_APP_NAME}
+
+    heroku addons:attach ${HEROKU_PG_DB_NAME} --credential api_user -a ${YOUR_APP_NAME}
+
+5.  Connect to the PostgreSQL database and create some sample data:
+
+  .. code-block:: bash
+
+    heroku psql -a ${YOUR_APP_NAME}
+
+  .. code-block:: postgres
+
+    # from the psql command prompt execute the following commands:
+    create schema api;
+
+    create table api.todos (
+    id serial primary key,
+    done boolean not null default false,
+    task text not null,
+    due timestamptz
+    );
+
+    insert into api.todos (task) values
+    ('finish tutorial 0'), ('pat self on back');
+
+    grant usage on schema api to api_user;
+    grant select on api.todos to api_user;
+
+6.  Create the :code:`Procfile`:
+
+  .. code-block:: bash
+
+    web: PGRST_SERVER_HOST=0.0.0.0 PGRST_SERVER_PORT=${PORT} PGRST_DB_URI=${PGRST_DB_URI:-${DATABASE_URL}} ./postgrest-${POSTGREST_VER}
+  ..
+
+  Set the following environment variables on Heroku:
+
+  .. code-block:: bash
+
+    heroku config:set POSTGREST_VER=10.0.0
+    heroku config:set PGRST_DB_SCHEMA=api
+    heroku config:set PGRST_DB_ANON_ROLE=api_user
+  ..
+
+  PGRST_DB_URI can be set if an external database is used or if it's different from the default Heroku DATABASE_URL. This latter is used if nothing is provided.
+  POSTGREST_VER is mandatory to select and build the required PostgREST release.
+
+  See https://postgrest.org/en/stable/configuration.html#environment-variables for the full list of environment variables.
+
+7.  Build and deploy your app:
+
+  .. code-block:: bash
+
+    git add Procfile
+    git commit -m "PostgREST on Heroku"
+    git push heroku master
+  ..
+
+  Your Heroku app should be live at :code:`${YOUR_APP_NAME}.herokuapp.com`
+
+8.  Test your app
+
+    From a terminal display the application logs:
+
+  .. code-block:: bash
+
+    heroku logs -t
+  ..
+
+  From a different terminal retrieve with curl the records previously created:
+
+  .. code-block:: bash
+
+    curl https://${YOUR_APP_NAME}.herokuapp.com/todos
+  ..
+
+  and test that any attempt to modify the table via a read-only user is not allowed:
+
+  .. code-block:: bash
+
+    curl https://${YOUR_APP_NAME}.herokuapp.com/todos -X POST \
+     -H "Content-Type: application/json" \
+     -d '{"task": "do bad thing"}'