From 2458d7b766aec78d69dac6f1f5b3147b762b4d4f Mon Sep 17 00:00:00 2001
From: Simon Willison <swillison@gmail.com>
Date: Thu, 8 Oct 2020 15:47:37 -0700
Subject: [PATCH] Docs on deploying with systemd, refs #514

---
 docs/deploying.rst | 84 ++++++++++++++++++++++++++++++++++++++++++++++
 docs/index.rst     |  1 +
 2 files changed, 85 insertions(+)
 create mode 100644 docs/deploying.rst

diff --git a/docs/deploying.rst b/docs/deploying.rst
new file mode 100644
index 00000000..9f049b06
--- /dev/null
+++ b/docs/deploying.rst
@@ -0,0 +1,84 @@
+.. _deploying:
+
+=====================
+ Deploying Datasette
+=====================
+
+The easiest way to deploy a Datasette instance on the internet is to use the ``datasette publish`` command, described in :ref:`publishing`. This can be used to quickly deploy Datasette to a number of hosting providers including Heroku, Google Cloud Run and Vercel.
+
+You can deploy Datasette to other hosting providers using the instructions on this page.
+
+.. _deploying_fundamentals:
+
+Deployment fundamentals
+=======================
+
+Datasette can be deployed as a single ``datasette`` process that listens on a port. Datasette is not designed to be run as root, so that process should listen on a higher port such as port 8000.
+
+If you want to serve Datasette on port 80 (the HTTP default port) or port 443 (for HTTPS) you should run it behind a proxy server, such as nginx, Apache or HAProxy. The proxy server can listen on port 80/443 and forward traffic on to Datasette.
+
+.. _deploying_systemd:
+
+Running Datasette using systemd
+===============================
+
+You can run Datasette on Ubuntu or Debian systems using ``systemd``.
+
+First, ensure you have Python 3 and ``pip`` installed. On Ubuntu you can use ``sudo apt-get install python3 python3-pip``.
+
+You can install Datasette into a virtual environment, or you can install it system-wide. To install system-wide, use ``sudo pip3 install datasette``.
+
+Now create a folder for your Datasette databases, for example using ``mkdir /home/ubuntu/datasette-root``.
+
+You can copy a test database into that folder like so::
+
+    cd /home/ubuntu/datasette-root
+    curl -O https://latest.datasette.io/fixtures.db
+
+Create a file at ``/etc/systemd/system/datasette.service`` with the following contents:
+
+.. code-block:: ini
+
+    [Unit]
+    Description=Datasette
+    After=network.target
+
+    [Service]
+    Type=simple
+    User=ubuntu
+    Environment=DATASETTE_SECRET=
+    WorkingDirectory=/home/ubuntu/datasette-root
+    ExecStart=datasette serve . -h 127.0.0.1 -p 8000
+    Restart=on-failure
+
+    [Install]
+    WantedBy=multi-user.target
+
+Add a random value for the ``DATASETTE_SECRET`` - this will be used to sign Datasette cookies such as the CSRF token cookie. You can generate a suitable value like so::
+
+    $ python3 -c 'import secrets; print(secrets.token_hex(32))'
+
+This configuration will run Datasette against all database files contained in the ``/home/ubunt/datasette-root`` directory. If that directory contains a ``metadata.yml`` (or ``.json``) file or a ``templates/`` or ``plugins/`` sub-directory those will automatically be loaded by Datasette - see :ref:`config_dir` for details.
+
+You can start the Datasette process running using the following::
+
+    sudo systemctl daemon-reload
+    sudo systemctl start datasette.service
+
+You can confirm that Datasette is running on port 8000 like so::
+
+    curl 127.0.01:8000/-/versions.json
+    # Should output JSON showing the installed version
+
+Datasette will not be accessible from outside the server because it is listening on ``127.0.0.1``. You can expose it by instead listening on ``0.0.0.0``, but a better way is to set up a proxy such as ``nginx``.
+
+Ubuntu offer `a tutorial on installing nginx <https://ubuntu.com/tutorials/install-and-configure-nginx#1-overview>`__. Once it is installed you can add configuration to proxy traffic through to Datasette that looks like this::
+
+    server {
+        server_name mysubdomain.myhost.net;
+
+        location / {
+            proxy_pass http://127.0.0.1:8000/;
+            proxy_set_header Host $host;
+        }
+    }
diff --git a/docs/index.rst b/docs/index.rst
index db87f029..9096efd9 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -40,6 +40,7 @@ Contents
    ecosystem
    pages
    publish
+   deploying
    json_api
    sql_queries
    authentication