From 0cdf111ae68d46eb2eb51d85e20e1447a42cbdcc Mon Sep 17 00:00:00 2001 From: Simon Willison Date: Mon, 4 May 2020 12:31:13 -0700 Subject: [PATCH] Move pip/pipx to top of installation instructions Less intimidating than Docker, hopefully. --- docs/installation.rst | 128 ++++++++++++++++++++++-------------------- 1 file changed, 67 insertions(+), 61 deletions(-) diff --git a/docs/installation.rst b/docs/installation.rst index 990d867b..c88950c2 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -11,67 +11,7 @@ on to your machine, or you can install it using Docker. .. contents:: -Using Docker ------------- - -A Docker image containing the latest release of Datasette is published to Docker -Hub here: https://hub.docker.com/r/datasetteproject/datasette/ - -If you have Docker installed (for example with `Docker for Mac -`_ on OS X) you can download and run this -image like so:: - - docker run -p 8001:8001 -v `pwd`:/mnt \ - datasetteproject/datasette \ - datasette -p 8001 -h 0.0.0.0 /mnt/fixtures.db - -This will start an instance of Datasette running on your machine's port 8001, -serving the ``fixtures.db`` file in your current directory. - -Now visit http://127.0.0.1:8001/ to access Datasette. - -(You can download a copy of ``fixtures.db`` from -https://latest.datasette.io/fixtures.db ) - -To upgrade to the most recent release of Datasette, run the following:: - - docker pull datasetteproject/datasette - -Loading Spatialite -~~~~~~~~~~~~~~~~~~ - -The ``datasetteproject/datasette`` image includes a recent version of the -:ref:`SpatiaLite extension ` for SQLite. To load and enable that -module, use the following command:: - - docker run -p 8001:8001 -v `pwd`:/mnt \ - datasetteproject/datasette \ - datasette -p 8001 -h 0.0.0.0 /mnt/fixtures.db \ - --load-extension=/usr/local/lib/mod_spatialite.so - -You can confirm that SpatiaLite is successfully loaded by visiting -http://127.0.0.1:8001/-/versions - -Installing plugins -~~~~~~~~~~~~~~~~~~ - -If you want to install plugins into your local Datasette Docker image you can do -so using the following recipe. This will install the plugins and then save a -brand new local image called ``datasette-with-plugins``:: - - docker run datasetteproject/datasette \ - pip install datasette-vega - - docker commit $(docker ps -lq) datasette-with-plugins - -You can now run the new custom image like so:: - - docker run -p 8001:8001 -v `pwd`:/mnt \ - datasette-with-plugins \ - datasette -p 8001 -h 0.0.0.0 /mnt/fixtures.db - -You can confirm that the plugins are installed by visiting -http://127.0.0.1:8001/-/plugins +.. _installation_pip: Install using pip ----------------- @@ -98,6 +38,8 @@ You can now run Datasette like so:: If you want to start making contributions to the Datasette project by installing a copy that lets you directly modify the code, take a look at our guide to :ref:`devenvironment`. +.. _installation_pipx: + Install using pipx ------------------ @@ -184,3 +126,67 @@ To upgrade a plugin within the pipx environment use ``pipx runpip datasette inst "version": "0.6.2" } ] + +.. _installation_docker: + +Using Docker +------------ + +A Docker image containing the latest release of Datasette is published to Docker +Hub here: https://hub.docker.com/r/datasetteproject/datasette/ + +If you have Docker installed (for example with `Docker for Mac +`_ on OS X) you can download and run this +image like so:: + + docker run -p 8001:8001 -v `pwd`:/mnt \ + datasetteproject/datasette \ + datasette -p 8001 -h 0.0.0.0 /mnt/fixtures.db + +This will start an instance of Datasette running on your machine's port 8001, +serving the ``fixtures.db`` file in your current directory. + +Now visit http://127.0.0.1:8001/ to access Datasette. + +(You can download a copy of ``fixtures.db`` from +https://latest.datasette.io/fixtures.db ) + +To upgrade to the most recent release of Datasette, run the following:: + + docker pull datasetteproject/datasette + +Loading Spatialite +~~~~~~~~~~~~~~~~~~ + +The ``datasetteproject/datasette`` image includes a recent version of the +:ref:`SpatiaLite extension ` for SQLite. To load and enable that +module, use the following command:: + + docker run -p 8001:8001 -v `pwd`:/mnt \ + datasetteproject/datasette \ + datasette -p 8001 -h 0.0.0.0 /mnt/fixtures.db \ + --load-extension=/usr/local/lib/mod_spatialite.so + +You can confirm that SpatiaLite is successfully loaded by visiting +http://127.0.0.1:8001/-/versions + +Installing plugins +~~~~~~~~~~~~~~~~~~ + +If you want to install plugins into your local Datasette Docker image you can do +so using the following recipe. This will install the plugins and then save a +brand new local image called ``datasette-with-plugins``:: + + docker run datasetteproject/datasette \ + pip install datasette-vega + + docker commit $(docker ps -lq) datasette-with-plugins + +You can now run the new custom image like so:: + + docker run -p 8001:8001 -v `pwd`:/mnt \ + datasette-with-plugins \ + datasette -p 8001 -h 0.0.0.0 /mnt/fixtures.db + +You can confirm that the plugins are installed by visiting +http://127.0.0.1:8001/-/plugins