diff --git a/docs/source/conf.py b/docs/source/conf.py index 3dc62000..f03af39c 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -57,9 +57,9 @@ author = u'Portainer.io' # built documents. # # The short X.Y version. -version = u'1.10.2' +version = u'1.11.0' # The full version, including alpha/beta/rc tags. -release = u'1.10.2' +release = u'1.11.0' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -133,7 +133,7 @@ html_theme = 'alabaster' # The name for this set of Sphinx documents. # " v documentation" by default. # -# html_title = u'Portainer v1.10.2' +# html_title = u'Portainer v1.11.0' # A shorter title for the navigation bar. Default is the same as html_title. # diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst index 0e703d7b..953a55ec 100644 --- a/docs/source/configuration.rst +++ b/docs/source/configuration.rst @@ -58,7 +58,6 @@ The following CLI flags are available: * ``--host``, ``-H``: Docker daemon endpoint (default: ``unix:///var/run/docker.sock``) * ``--bind``, ``-p``: Address and port to serve Portainer (default: ``:9000``) -* ``--swarm``, ``-s``: Docker Swarm cluster / swarm-mode support (default: ``false``) * ``--tlsverify``: TLS support (default: ``false``) * ``--tlscacert``: Path to the CA (default: ``/certs/ca.pem``) * ``--tlscert``: Path to the TLS certificate file (default: ``/certs/cert.pem``) diff --git a/docs/source/deployment.rst b/docs/source/deployment.rst index 35fcce99..54bcb713 100644 --- a/docs/source/deployment.rst +++ b/docs/source/deployment.rst @@ -12,20 +12,33 @@ Portainer deployment scenarios can be executed on both platforms unless specifie Quick start =========== -The most common deployment scenario is to deploy Portainer to manage a remote Docker host, it's as simple as: +Deploying Portainer is as simple as: .. code-block:: bash - $ docker run -d -p 9000:9000 portainer/portainer -H tcp://: + $ docker run -d -p 9000:9000 portainer/portainer Voilà, you can now access Portainer by pointing your web browser at ``http://DOCKER_HOST:9000`` Ensure you replace ``DOCKER_HOST`` with address of your Docker host where Portainer is running. -Connect to a remote Docker engine -================================= +You'll then be prompted to specify a new password for the ``admin`` account. After specifying your password, +you'll then be able to connect to the Portainer UI. -In order to connect to a remote host, use the ``-H`` flag and the ``tcp://`` protocol: +Manage a new endpoint +===================== + +After your first authentication, Portainer will ask you information about the Docker endpoint you want to manage. + +You'll have the following choices: + +* Manage the local engine where Portainer is running (you'll need to bind mount the Docker socket via `-v /var/run/docker.sock:/var/run/docker.sock` on the Docker CLI) +* Manage a remote Docker engine, you'll just have to specify the url to your Docker endpoint, give it a name and TLS info if needed + +Declare initial endpoint via CLI +================================ + +You can specify the initial endpoint you want Portainer to manage via the CLI, use the ``-H`` flag and the ``tcp://`` protocol to connect to a remote Docker endpoint: .. code-block:: bash @@ -33,47 +46,26 @@ In order to connect to a remote host, use the ``-H`` flag and the ``tcp://`` pro Ensure you replace ``REMOTE_HOST`` and ``REMOTE_PORT`` with the address/port of the Docker engine you want to manage. -Connect to a local Docker engine -================================ - -*Docker for Linux only* - -By default, Portainer will try to connect to the local Docker engine using the unix socket path at ``/var/run/docker.sock`` - -You will need to bind mount the Docker socket to manage a local Docker engine: +You can also bind mount the Docker socket to manage a local Docker engine: .. code-block:: bash $ docker run -d -p 9000:9000 -v /var/run/docker.sock:/var/run/docker.sock portainer/portainer - -If your host is using SELinux, you'll need to pass the ``--privileged`` flag to the Docker run command: +**Note**: If your host is using SELinux, you'll need to pass the ``--privileged`` flag to the Docker run command: .. code-block:: bash $ docker run -d -p 9000:9000 --privileged -v /var/run/docker.sock:/var/run/docker.sock portainer/portainer -You can also specify an alternative path to the Docker socket using the ``-H`` flag combined with the ``unix://`` protocol: - -.. code-block:: bash - - $ docker run -d -p 9000:9000 -v /var/run/docker.sock:/docker/docker.sock portainer/portainer -H unix:///docker/docker.sock - Connect to a Swarm cluster ========================== -If you want to manage a cluster created with Docker Swarm or using the swarm mode of Docker 1.12 all you need to do -is to add the ``--swarm`` flag to the portainer command line. +Portainer will automatically detect if your endpoint is part of a Swarm cluster (either Docker Swarm or Swarm mode). **Note**: Ensure you connect to either a *primary* node when connecting to a Docker Swarm cluster or a *manager* node when connecting to a cluster created with Docker swarm mode. -For example, when connecting to a remote Swarm node: - -.. code-block:: bash - - $ docker run -d -p 9000:9000 portainer/portainer -H tcp://: --swarm - If you're using swarm mode, you can also deploy it as a service in your cluster: .. code-block:: bash @@ -84,14 +76,14 @@ If you're using swarm mode, you can also deploy it as a service in your cluster: --constraint 'node.role == manager' \ --mount type=bind,src=/var/run/docker.sock,dst=/var/run/docker.sock \ portainer/portainer \ - --swarm + -H unix:///var/run/docker.sock Connect to a Docker engine with TLS enabled =========================================== If your Docker engine is protected using TLS, you'll need to ensure that you have access to CA, the certificate and the public key used to access your Docker engine. -You can then use the ``--tlsverify`` flag to enable TLS communication with the Docker API. +You can upload the required files via the Portainer UI or use the ``--tlsverify`` flag on the CLI. Portainer will try to use the following paths to the files specified previously: @@ -108,9 +100,22 @@ You must ensure these files are present in the container using a bind mount: You can also use the ``--tlscacert``, ``--tlscert`` and ``--tlskey`` flags if you want to change the default path to the CA, certificate and key file respectively: .. code-block:: bash - + $ docker run -d -p 9000:9000 -v /path/to/certs:/certs portainer/portainer -H tcp://: --tlsverify --tlscacert /certs/myCa.pem --tlscert /certs/myCert.pem --tlskey /certs/myKey.pem +Persist Portainer data +====================== + +By default, Portainer will store its data inside the container in the `/data` folder (this can be changed via CLI, see configuration). + +You'll need to persist Portainer data to keep your changes after restart/upgrade of the Portainer container. You can use a bind mount +to persist the data on the Docker host folder: + +.. code-block:: bash + + $ docker run -d -p 9000:9000 -v /path/on/host/data:/data portainer/portainer + + Without Docker ============== @@ -121,8 +126,8 @@ Download and extract the binary to a location on disk: .. code-block:: bash $ cd /opt - $ wget https://github.com/portainer/portainer/releases/download/1.10.2/portainer-1.10.2-linux-amd64.tar.gz - $ tar xvpfz portainer-1.10.2-linux-amd64.tar.gz + $ wget https://github.com/portainer/portainer/releases/download/1.11.0/portainer-1.11.0-linux-amd64.tar.gz + $ tar xvpfz portainer-1.11.0-linux-amd64.tar.gz Then just use the portainer binary as you would use CLI flags with Docker. diff --git a/docs/source/faq.rst b/docs/source/faq.rst index d8f3ac5b..3d779276 100644 --- a/docs/source/faq.rst +++ b/docs/source/faq.rst @@ -31,46 +31,6 @@ Here is a working configuration for Nginx (tested on 1.11) to serve Portainer at Replace ``ADDRESS:PORT`` with the Portainer server/container details. -How can I setup basic HTTP authentication in front of Portainer? -================================================================= - -Here is a working configuration for Nginx (tested on 1.11 with **bcrypt** support) to serve Portainer at `myhost.mydomain/portainer` with basic HTTP authentication: - -.. code-block:: nginx - - upstream portainer { - server ADDRESS:PORT; - } - - server { - listen 80; - - auth_basic "myhost.mydomain/portainer"; - auth_basic_user_file /etc/nginx/conf.d/portainer.htpasswd; - - location /portainer/ { - proxy_http_version 1.1; - proxy_set_header Connection ""; - proxy_pass http://portainer/; - } - location /portainer/ws/ { - proxy_set_header Upgrade $http_upgrade; - proxy_set_header Connection "upgrade"; - proxy_http_version 1.1; - proxy_pass http://portainer/ws/; - } - } - -Replace ``ADDRESS:PORT`` with the Portainer server/container details. - -You can generate the authentication file using the following command: - -.. code-block:: bash - - docker run --rm httpd htpasswd -nbB /etc/nginx/conf.d/portainer.htpasswd - -You can also checkout our pre-configured setup using Docker compose `here `_. - How can I configure my reverse proxy to serve Portainer using HAProxy? ====================================================================== @@ -152,9 +112,18 @@ Have a look at the `Docker documentation ` -Portainer has to be connected to a Docker instance either by bind-mounting the Docker socket or using the ``-H`` flag in the container command to specify -the Docker host address. Unfortunately, Kitematic does not allow you to specify any of these at the moment. +How can I use a custom CSS file to customize Portainer look? +============================================================ + +A workaround can be used to specify your own `vendor.css` and `portainer.css` files. Simply bind mount the folder of your choice +to the `css` folder inside the container: + +.. code-block:: bash + + $ docker run -d -p 9000:9000 -v /css:/css/ portainer/portainer