diff --git a/SUMMARY.md b/SUMMARY.md index 6e314625..f9c40a4d 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -275,6 +275,7 @@ * [Using Portainer with reverse proxies](advanced/reverse-proxy/README.md) * [Deploying Portainer behind Traefik Proxy](advanced/reverse-proxy/traefik.md) * [Deploying Portainer behind nginx reverse proxy](advanced/reverse-proxy/nginx.md) +* [How Relative Path Support Works in Portainer](advanced/relative-paths.md) * [Helm chart configuration options](advanced/helm-chart-configuration-options.md) * [Docker roles and permissions](advanced/docker-roles-and-permissions.md) * [Kubernetes roles and bindings](advanced/kubernetes-roles-and-bindings.md) diff --git a/advanced/cli.md b/advanced/cli.md index 51a48c03..a9a46732 100644 --- a/advanced/cli.md +++ b/advanced/cli.md @@ -2,37 +2,37 @@ ## Configuration flags available at the command line -| Flag | Description | -| ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `--admin-password` | Specifies a bcrypt hashed password for the admin user. This can only be used when first creating the admin user (such as during installation) and not to change the admin user's password after installation. | -| `--admin-password-file` | Specifies the path to the file containing the password for the admin user. This can only be used when first creating the admin user (such as during installation) and not to change the admin user's password after installation. | -| `--base-url` | Specifies the path that Portainer is running under if you are running Portainer within a subpath (for example use `--baseurl /portainer` if you are running Portainer at `https://yourdomain/portainer`). Defaults to `/`. | -|

--bind

-p

| Specifies the address and port from which to serve Portainer (default: `:9000`). | -| `--bind-https` | Specifies the address and port from which to serve Portainer via HTTPS (default: `:9443`). | -|

--data

-d

| Specifes the directory where Portainer data will be stored (default: `/data` on Linux, `C:\data` on Windows). | -| `--edge-compute` | Automatically enables Edge Compute features. | -|

--hide-label

-l

| Hides containers with a specific label in the UI. | -| `--http-disabled` | Serve Portainer only on HTTPS. Overrides `--http-enabled`. Ensure your HTTPS configuration is fully working and any agents are configured for HTTPS before enabling this. | -| `--http-enabled` | Serve Portainer on HTTP. If used in combination with `--http-disabled`, this is ignored. | -|

--host

-H

| Specifies the Docker daemon endpoint. | -| `--license-key` | Specifies the license key to use. Only applicable to Portainer Business Edition. | -| `--logo` | Specifies the URL to the image to be displayed as a logo in the UI. If not specified, the Portainer logo is used instead. | -| `--mtlscacert` | Specifies the path to the certificate authority (CA) certificate used for mTLS communication. | -| `--mtlscert` | Specifies the path to the certificate used for mTLS communication. | -| `--mtlskey` | Specifies the path to the certificate key used for mTLS communication. | -| `--snapshot-interval` | Specifies the time interval between two environment snapshot jobs expressed as a string. For example 30s, 5m, 1h… Supported by the `time.ParseDuration` method (default: 5m). | -| `--sslcacert` | Specifies the path to the certificate authority (CA) certificate used to secure the Portainer instance. | -| `--sslcert` | Specifies the path to the SSL certificate used to secure the Portainer instance (default: `/certs/portainer.crt` on Linux, `C:\certs\portainer.crt` on Windows). | -| `--sslkey` | Specifies the path to the SSL key used to secure the Portainer instance (default: `/certs/portainer.key` on Linux, `C:\certs\portainer.key` on Windows). | -|

--templates

-t

| Specifies the URL to the templates (apps) definitions. | -| `--tlscacert` | Specifies the path to the CA used for Docker daemon connections (default: `/certs/ca.pem` on Linux, `C:\certs\ca.pem` on Windows). | -| `--tlscert` | Specifies the path to the TLS certificate file used for Docker daemon connections (default: `/certs/cert.pem`, `C:\certs\cert.pem` on Windows). | -| `--tlskey` | Specifies the path to the TLS key used for Docker daemon connections (default: `/certs/key.pem`, `C:\certs\key.pem` on Windows). | -| `--tlsverify` | TLS support (default: `false`). | -| `--tlsskipverify` | Disable TLS server verification. | -| `--tunnel-addr` | Specifies the tunnel address to listen on for use with the Edge Agent. Defaults to `0.0.0.0` (all interfaces). | -| `--tunnel-port` | Specifies an alternate tunnel port to use with the Edge Agent. Use `--tunnel-port 8001` with `-p 8001:8001` to make the Edge Agent communicate on port `8001`. | -| `--version` | Display the version of Portainer. | +| Flag | Description | +| ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `--admin-password` | Specifies a bcrypt hashed password for the admin user. This can only be used when first creating the admin user (such as during installation) and not to change the admin user's password after installation. | +| `--admin-password-file` | Specifies the path to the file containing the password for the admin user. This can only be used when first creating the admin user (such as during installation) and not to change the admin user's password after installation. | +| `--base-url` |

Specifies the path that Portainer is running under if you are running Portainer within a subpath behind a reverse proxy (for example use --base-url /portainer if you are running Portainer at https://yourdomain/portainer). Defaults to /.
Note: when using this option you will still need to ensure your reverse proxy configuration will strip the specified subpath.

| +|

--bind

-p

| Specifies the address and port from which to serve Portainer (default: `:9000`). | +| `--bind-https` | Specifies the address and port from which to serve Portainer via HTTPS (default: `:9443`). | +|

--data

-d

| Specifes the directory where Portainer data will be stored (default: `/data` on Linux, `C:\data` on Windows). | +| `--edge-compute` | Automatically enables Edge Compute features. | +|

--hide-label

-l

| Hides containers with a specific label in the UI. | +| `--http-disabled` | Serve Portainer only on HTTPS. Overrides `--http-enabled`. Ensure your HTTPS configuration is fully working and any agents are configured for HTTPS before enabling this. | +| `--http-enabled` | Serve Portainer on HTTP. If used in combination with `--http-disabled`, this is ignored. | +|

--host

-H

| Specifies the Docker daemon endpoint. | +| `--license-key` | Specifies the license key to use. Only applicable to Portainer Business Edition. | +| `--logo` | Specifies the URL to the image to be displayed as a logo in the UI. If not specified, the Portainer logo is used instead. | +| `--mtlscacert` | Specifies the path to the certificate authority (CA) certificate used for mTLS communication. | +| `--mtlscert` | Specifies the path to the certificate used for mTLS communication. | +| `--mtlskey` | Specifies the path to the certificate key used for mTLS communication. | +| `--snapshot-interval` | Specifies the time interval between two environment snapshot jobs expressed as a string. For example 30s, 5m, 1h… Supported by the `time.ParseDuration` method (default: 5m). | +| `--sslcacert` | Specifies the path to the certificate authority (CA) certificate used to secure the Portainer instance. | +| `--sslcert` | Specifies the path to the SSL certificate used to secure the Portainer instance (default: `/certs/portainer.crt` on Linux, `C:\certs\portainer.crt` on Windows). | +| `--sslkey` | Specifies the path to the SSL key used to secure the Portainer instance (default: `/certs/portainer.key` on Linux, `C:\certs\portainer.key` on Windows). | +|

--templates

-t

| Specifies the URL to the templates (apps) definitions. | +| `--tlscacert` | Specifies the path to the CA used for Docker daemon connections (default: `/certs/ca.pem` on Linux, `C:\certs\ca.pem` on Windows). | +| `--tlscert` | Specifies the path to the TLS certificate file used for Docker daemon connections (default: `/certs/cert.pem`, `C:\certs\cert.pem` on Windows). | +| `--tlskey` | Specifies the path to the TLS key used for Docker daemon connections (default: `/certs/key.pem`, `C:\certs\key.pem` on Windows). | +| `--tlsverify` | TLS support (default: `false`). | +| `--tlsskipverify` | Disable TLS server verification. | +| `--tunnel-addr` | Specifies the tunnel address to listen on for use with the Edge Agent. Defaults to `0.0.0.0` (all interfaces). | +| `--tunnel-port` | Specifies an alternate tunnel port to use with the Edge Agent. Use `--tunnel-port 8001` with `-p 8001:8001` to make the Edge Agent communicate on port `8001`. | +| `--version` | Display the version of Portainer. | ## Creating an admin account and password diff --git a/advanced/relative-paths.md b/advanced/relative-paths.md new file mode 100644 index 00000000..8582c8bf --- /dev/null +++ b/advanced/relative-paths.md @@ -0,0 +1,86 @@ +# How Relative Path Support Works in Portainer + +The relative path volumes support in Portainer is intended to provide you with a way to reference files and directories that are supplied within the Git repository alongside your compose file without needing to know the absolute path at which they will appear when they are deployed to your environment. In the background the way this works is as follows: + +1. In Portainer, a stack deployment is initiated where the stack is located in a Git repository, **Enable relative path volumes** is selected and a **Local (or Network) filesystem path** is specified. +2. Portainer creates a temporary unpacker container that bind mounts the path specified in the Local (or Network) filesystem path field. +3. The unpacker container clones the Git repository to a subdirectory under the bind mounted path. +4. Portainer creates the stack using the compose file provided, specifying the working directory as where the specified compose file is located within where the Git repo was cloned. +5. Now that the stack has been deployed, the temporary unpacker container is removed. + +To take advantage of this with your compose file, you can specify any references to files that are within your repository in a _relative_ manner to your compose file. For example, imagine this simple nginx deployment: + +``` +. +├── docker-compose.yml +└── static + └── index.html +``` + +In this example, the `docker-compose.yml` file is at the base directory of the repository. Alongside it there is a directory named `static`, and within that directory is an `index.html` file. + +The `docker-compose.yml` file looks like this: + +``` +version: '3.1' +services: + webapp: + image: nginx:latest + restart: always + ports: + - "3002:80" + volumes: + - ./static:/usr/share/nginx/html +``` + +The last line is the important one here - you'll note that we're referencing the static directory with a leading `.` and `/` - this tells compose that the path specified is _relative_ to the working directory, which Portainer specified during deployment. If we excluded the leading `.` this would be an _absolute_ path, and would refer to `/static` at the root of the host filesystem. + +Let's look at an example where you had your compose file in a subdirectory of your repository, and your content in a different subdirectory: + +``` +. +├── nginx +│ └── docker-compose.yml +└── static + └── index.html +``` + +In this scenario, you would specify the compose file when deploying as `nginx/docker-compose.yml`. Portainer will pull the contents of the repository to the specified location and set the working directory to the location of the compose file (ie, within the `nginx` subdirectory). As such, relative references within the compose need to be aware of this. To mount the contents of the `static` directory, your compose file would look like: + +``` +version: '3.1' +services: + webapp: + image: nginx:latest + restart: always + ports: + - "3002:80" + volumes: + - ../static:/usr/share/nginx/html +``` + +The double dots (`..`) indicate that the files are at a directory level above the working directory. + +### A note about the local (or network) filesystem path + +The path on the local (or network) filesystem that the Git repository is cloned to will be in: + +``` +portainer-compose-unpacker/stacks/yourstackname/ +``` + +For example, if you deployed a stack named `nginx` and specified the local filesystem path as: + +``` +/mnt/stacks/ +``` + +it would result in: + +``` +/mnt/stacks/portainer-compose-unpacker/stacks/nginx/ +``` + +This is generally not relevant for relative path referencing as the definition of the working directory avoids needing to be aware of this full path, but it does mean the same local (or network) filesystem path can be used to deploy multiple stacks without worrying about collisions (as long as they don't share the same stack name). + +This path is where your stack's mounted files will be sourced from, so you will want to ensure this path remains intact and unchanged. When a stack deployed with this method is removed, the file and directory structure for that stack are removed as well. diff --git a/user/docker/stacks/add.md b/user/docker/stacks/add.md index a14c8834..a6e1afca 100644 --- a/user/docker/stacks/add.md +++ b/user/docker/stacks/add.md @@ -184,6 +184,10 @@ Ensure that this path is available on all of your Docker Swarm nodes and is writ
+{% hint style="info" %} +For more detail on how this feature works, have a look at [this article](../../../advanced/relative-paths.md). +{% endhint %} + ### Environment variables As an optional step, you can also set environment variables. You can use these to define values in your compose file that would vary between deployments (for example, hostnames, database names, etc). diff --git a/user/edge/stacks/add.md b/user/edge/stacks/add.md index 430adb79..ca1b260d 100644 --- a/user/edge/stacks/add.md +++ b/user/edge/stacks/add.md @@ -126,6 +126,10 @@ Ensure that this path is available on all of your Docker Swarm nodes and is writ
+{% hint style="info" %} +For more detail on how this feature works, have a look at [this article](../../../advanced/relative-paths.md). +{% endhint %} + ### GitOps Edge configurations When relative path volumes are enabled, you can also choose to deploy device-specific configurations from your Git repository to the devices your Edge stack will be deployed to. To use this, enable the **GitOps Edge configurations** toggle, enter the **Directory** (relative to the root of your Git repository) and select the **Matching rule** that corresponds to your configuration.