Deploying to gh-pages from @ dc7a04a 🚀

en/docs/installation-docker/index.html

@@ -9,4 +9,4 @@
         height: 100vh;
       }</style><aside id="content-toc" class="w-48 sticky docs-toc order-3 flex-shrink-0"><span class="block uppercase text-gray-600 font-bold text-xs tracking-wider pt-0">Contents</span><nav class="toc"><ol><li><a href="#setup-with-docker-compose">Setup with Docker Compose</a><ol><li><a href="#configuring-docker-compose.yml">Configuring docker-compose.yml</a><ol><li><a href="#port">Port</a></li><li><a href="#environment-variables">Environment variables</a></li><li><a href="#volumes">Volumes</a></li></ol></li><li><a href="#running-docker-compose.yml">Running docker-compose.yml</a></li></ol></li><li><a href="#docker-tags-and-versioning">Docker tags and versioning</a></li><li><a href="#updating">Updating</a></li></ol></nav></aside><main id="primary-content" class="mb-40 w-full px-14 py-14"><header class="flex justify-between items-center"><h1>Setup with Docker</h1><div class="flex items-center"><a title="Edit on GitHub" class="text-gray-500 hover:text-primaryDark no-underline" href="https://github.com/photoview/photoview.github.io/edit/master/./src/en/docs/installation-docker.md"><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-edit-3"><path d="M12 20h9"></path><path d="M16.5 3.5a2.121 2.121 0 0 1 3 3L7 19l-4 1 1-4L16.5 3.5z"></path></svg> </a><select class="ml-5" id="lg-switcher" onchange="changeLanguage()"><option class="lg-switcher-item" selected="selected" value="/en/docs/installation-docker/">English</option><option class="lg-switcher-item" value="/fr/docs/installation-docker/">Français</option></select><script>function changeLanguage() {
       document.location.href=document.getElementById("lg-switcher").value;
-    }</script></div></header><p>By far the easiest way to get up and running with Photoview is by running it inside a Docker container. With Docker, all dependencies are automatically installed and ready to go. If you are completeley new to Docker and want to learn more, check out this <a href="https://www.freecodecamp.org/news/docker-simplified-96639a35ff36/">article by FreeCodeCamp</a>.</p><p>To better organise the Docker containers, a tool called <a href="https://docs.docker.com/compose/">Docker Compose</a> can be used. This lets you configure containers in a <code>yaml</code> file, and quickly start all the configured containers at once. Although this tool can't do anything you can't already to with Docker alone, it simplifes the process.</p><h2 id="setup-with-docker-compose" tabindex="-1"><a class="header-anchor" href="#setup-with-docker-compose" aria-label="Anchor"></a> Setup with Docker Compose</h2><blockquote><p>Prerequisite: Docker Engine and Docker Compose is installed on your server. See <a href="https://docs.docker.com/engine/install/">Install Docker Engine</a> and <a href="https://docs.docker.com/compose/install/">Install Docker Compose</a> on how to do so.</p></blockquote><p>To configure Photoview using Docker Compose, first copy the contents of <a href="https://github.com/photoview/photoview/blob/master/docker-compose.example.yml">docker-compose.example.yml</a>, and save it to a file called <code>docker-compose.yml</code>.</p><p>Within the file you will find two services: the Photoview server itself named <code>photoview</code> and a MariaDB database named <code>db</code>. The Photoview service is already configured with the database.</p><h3 id="configuring-docker-compose.yml" tabindex="-1"><a class="header-anchor" href="#configuring-docker-compose.yml" aria-label="Anchor"></a> Configuring docker-compose.yml</h3><p>The compose file is setup to work without any modifications. If you just want to get started skip to the <a href="#running-docker-compose.yml">next section</a>.</p><p>But you might want to make a few changes to fit your setup:</p><h4 id="port" tabindex="-1"><a class="header-anchor" href="#port" aria-label="Anchor"></a> Port</h4><p>You can change the port that Photoview will be running on under <code>services.photoview.ports</code>. By default the value is <code>8000:80</code>, this means that port <code>80</code> inside the container will be mapped to <code>8000</code> on the host machine. Eg. if you want your instance to run on port <code>1234</code> instead, change the value to <code>1234:80</code>. Notice that the port inside the container <code>80</code> matches the value of <code>PHOTOVIEW_LISTEN_PORT=80</code> under <code>services.photoview.environment</code>.</p><h4 id="environment-variables" tabindex="-1"><a class="header-anchor" href="#environment-variables" aria-label="Anchor"></a> Environment variables</h4><p>Under <code>services.photoview.environment</code> a number of environment variables are defined to configure various parts of Photoview. For a detailed description of all available environment variables, see <a href="/en/docs/installation-environment-variables/">Environment variables</a>.</p><p>One thing that you might want to configure here is the <code>MAPBOX_TOKEN</code> variable. This is needed if you want to use map related features, like the Places page. A token can be generated for free on <a href="https://account.mapbox.com/access-tokens/">Mapbox's website</a>, after you create an account.</p><h4 id="volumes" tabindex="-1"><a class="header-anchor" href="#volumes" aria-label="Anchor"></a> Volumes</h4><p>For Photoview to find your media, your files must be mounted inside the Photoview container using one or more <a href="https://docs.docker.com/storage/bind-mounts/">bind mounts</a>. This is configured under the <code>services.photoview.volumes</code> path in the <code>docker-compose.yml</code> file.</p><p>By default the only bind mount is: <code>./photos_path:/photos:ro</code>.</p><p>This line should be interpreted as <code>&lt;HOST_PATH&gt;:&lt;CONTAINER_PATH&gt;:ro</code>, it means that <code>&lt;HOST_PATH&gt;</code> on your machine will be accessible as <code>&lt;CONTAINER_PATH&gt;</code> inside the Photoview container. When you later have to configure where Photoview should look for your files, you should provide the path within the container, ie. the <code>&lt;CONTAINER_PATH&gt;</code>.</p><p>The <code>:ro</code> part at the end, means that the files will be mounted as <code>read-only</code> and it will not be possible for Photoview to change your files. Although this part is optional, it is recommended to increase security.</p><p>You can add as many bind mounts as you'd like. For example if your media is stored in the <code>Pictures</code> directory of your home user, you might want to add a bind mount like so: <code>/home/ben/Pictures:/bens_pictures</code>. Now the media will be accessible from <code>/bens_pictures</code> within the container.</p><h3 id="running-docker-compose.yml" tabindex="-1"><a class="header-anchor" href="#running-docker-compose.yml" aria-label="Anchor"></a> Running docker-compose.yml</h3><p>To start the docker containers specified inside the <code>docker-compose.yml</code> file, run the following command:</p><pre class="language-shell"><code class="language-shell">$ docker-compose up -d</code></pre><p>This will start the containers, <code>-d</code> means that it will do this in the background. When the system has started, you can access it from <code>http://localhost:8000</code>, unless you specified a custom port.</p><p>Below are some other commonly used Docker Compose commands.</p><pre class="language-shell"><code class="language-shell">$ docker-compose down <span class="token comment"># stop the containers</span><br>$ docker-compose logs <span class="token comment"># show the logs of the containers</span><br>$ docker-compose <span class="token function">ps</span>   <span class="token comment"># show status of the running containers</span></code></pre><h2 id="docker-tags-and-versioning" tabindex="-1"><a class="header-anchor" href="#docker-tags-and-versioning" aria-label="Anchor"></a> Docker tags and versioning</h2><p>The version of Photoview, when running Docker, can be specified using a tag. There exists the following tags:</p><ul><li><code>latest</code>, this is the latest released version.</li><li><code>edge</code>, this reflects the master branch and thus might include unreleased and unfinished features. It is not recommended to use this in production.</li></ul><p>Besides those tags, a particular version can be specified. This is done using the following formatting: <code>x.y.z</code> (eg. <code>2.3.5</code>) or <code>x.y</code> (eg. <code>2.3</code>) or <code>x</code> (eg. <code>2</code>), where:</p><ul><li><code>x</code> is the major version, each major version is not compatiable with the previous.</li><li><code>y</code> is the minor version, each minor version includes bigger features and changes, but it keeps compatibility.</li><li><code>z</code> is the patch version, a patch version only includes bug fixes and minor improvements.</li></ul><p>If a full version is specified, for example <code>2.3.6</code>, then that corresponds with that specific release and that image will never change. But if only <code>2.3</code> that represents the latest patch version for <code>2.3.z</code>, thus if a <code>2.3.7</code> is released, <code>2.3</code> will also be updated. Lastly <code>2</code> would be the latest version within the major version.</p><p>It is recommended to use version <code>2</code> for most circumstances, as in that way you get the latest updates, but your system will not break after an automatic update.</p><h2 id="updating" tabindex="-1"><a class="header-anchor" href="#updating" aria-label="Anchor"></a> Updating</h2><p>To update Photoview running in a docker-compose environment, simply run the following commands:</p><pre class="language-bash"><code class="language-bash">$ docker-compose pull    <span class="token comment"># Pull the latest images</span><br>$ docker-compose up -d   <span class="token comment"># Restart and update the containers whose images has changed</span></code></pre></main></div></div><div id="search-overlay" class="hidden"><div id="search-dimmer" class="fixed top-0 left-0 w-full h-full bg-black opacity-10"></div><div class="fixed top-20 left-1/2 transform -translate-x-1/2 bg-white shadow-lg border border-gray-200 rounded-md p-4 w-40rem overflow-y-auto h-3/4" role="dialog"><input id="search-field" type="search" class="mb-4 w-full py-2 px-3 text-sm border border-gray-200 rounded-md" placeholder="Search" aria-autocomplete="list" autocomplete="off" autocorrect="off" autocapitalize="none" spellcheck="false" enterkeyhint="search" aria-controls="search-results-box"><div role="listbox" aria-label="Search" id="search-results-box" class="">Loading results...</div></div></div><script defer="defer" src="/docs/docs-scripts.js"></script></body></html>
+    }</script></div></header><p>By far the easiest way to get up and running with Photoview is by running it inside a Docker container. With Docker, all dependencies are automatically installed and ready to go. If you are completeley new to Docker and want to learn more, check out this <a href="https://www.freecodecamp.org/news/docker-simplified-96639a35ff36/">article by FreeCodeCamp</a>.</p><p>To better organise the Docker containers, a tool called <a href="https://docs.docker.com/compose/">Docker Compose</a> can be used. This lets you configure containers in a <code>yaml</code> file, and quickly start all the configured containers at once. Although this tool can't do anything you can't already to with Docker alone, it simplifes the process.</p><h2 id="setup-with-docker-compose" tabindex="-1"><a class="header-anchor" href="#setup-with-docker-compose" aria-label="Anchor"></a> Setup with Docker Compose</h2><blockquote><p>Prerequisite: Docker Engine and Docker Compose is installed on your server. See <a href="https://docs.docker.com/engine/install/">Install Docker Engine</a> and <a href="https://docs.docker.com/compose/install/">Install Docker Compose</a> on how to do so.</p></blockquote><p>To configure Photoview using Docker Compose, first copy the contents of <a href="https://github.com/photoview/photoview/blob/master/docker-compose%20example/docker-compose.example.yml">docker-compose.example.yml</a>, and save it to a file called <code>docker-compose.yml</code>.</p><p>Within the file you will find two services: the Photoview server itself named <code>photoview</code> and a MariaDB database named <code>db</code>. The Photoview service is already configured with the database.</p><h3 id="configuring-docker-compose.yml" tabindex="-1"><a class="header-anchor" href="#configuring-docker-compose.yml" aria-label="Anchor"></a> Configuring docker-compose.yml</h3><p>The compose file is setup to work without any modifications. If you just want to get started skip to the <a href="#running-docker-compose.yml">next section</a>.</p><p>But you might want to make a few changes to fit your setup:</p><h4 id="port" tabindex="-1"><a class="header-anchor" href="#port" aria-label="Anchor"></a> Port</h4><p>You can change the port that Photoview will be running on under <code>services.photoview.ports</code>. By default the value is <code>8000:80</code>, this means that port <code>80</code> inside the container will be mapped to <code>8000</code> on the host machine. Eg. if you want your instance to run on port <code>1234</code> instead, change the value to <code>1234:80</code>. Notice that the port inside the container <code>80</code> matches the value of <code>PHOTOVIEW_LISTEN_PORT=80</code> under <code>services.photoview.environment</code>.</p><h4 id="environment-variables" tabindex="-1"><a class="header-anchor" href="#environment-variables" aria-label="Anchor"></a> Environment variables</h4><p>Under <code>services.photoview.environment</code> a number of environment variables are defined to configure various parts of Photoview. For a detailed description of all available environment variables, see <a href="/en/docs/installation-environment-variables/">Environment variables</a>.</p><p>One thing that you might want to configure here is the <code>MAPBOX_TOKEN</code> variable. This is needed if you want to use map related features, like the Places page. A token can be generated for free on <a href="https://account.mapbox.com/access-tokens/">Mapbox's website</a>, after you create an account.</p><h4 id="volumes" tabindex="-1"><a class="header-anchor" href="#volumes" aria-label="Anchor"></a> Volumes</h4><p>For Photoview to find your media, your files must be mounted inside the Photoview container using one or more <a href="https://docs.docker.com/storage/bind-mounts/">bind mounts</a>. This is configured under the <code>services.photoview.volumes</code> path in the <code>docker-compose.yml</code> file.</p><p>By default the only bind mount is: <code>./photos_path:/photos:ro</code>.</p><p>This line should be interpreted as <code>&lt;HOST_PATH&gt;:&lt;CONTAINER_PATH&gt;:ro</code>, it means that <code>&lt;HOST_PATH&gt;</code> on your machine will be accessible as <code>&lt;CONTAINER_PATH&gt;</code> inside the Photoview container. When you later have to configure where Photoview should look for your files, you should provide the path within the container, ie. the <code>&lt;CONTAINER_PATH&gt;</code>.</p><p>The <code>:ro</code> part at the end, means that the files will be mounted as <code>read-only</code> and it will not be possible for Photoview to change your files. Although this part is optional, it is recommended to increase security.</p><p>You can add as many bind mounts as you'd like. For example if your media is stored in the <code>Pictures</code> directory of your home user, you might want to add a bind mount like so: <code>/home/ben/Pictures:/bens_pictures</code>. Now the media will be accessible from <code>/bens_pictures</code> within the container.</p><h3 id="running-docker-compose.yml" tabindex="-1"><a class="header-anchor" href="#running-docker-compose.yml" aria-label="Anchor"></a> Running docker-compose.yml</h3><p>To start the docker containers specified inside the <code>docker-compose.yml</code> file, run the following command:</p><pre class="language-shell"><code class="language-shell">$ docker-compose up -d</code></pre><p>This will start the containers, <code>-d</code> means that it will do this in the background. When the system has started, you can access it from <code>http://localhost:8000</code>, unless you specified a custom port.</p><p>Below are some other commonly used Docker Compose commands.</p><pre class="language-shell"><code class="language-shell">$ docker-compose down <span class="token comment"># stop the containers</span><br>$ docker-compose logs <span class="token comment"># show the logs of the containers</span><br>$ docker-compose <span class="token function">ps</span>   <span class="token comment"># show status of the running containers</span></code></pre><h2 id="docker-tags-and-versioning" tabindex="-1"><a class="header-anchor" href="#docker-tags-and-versioning" aria-label="Anchor"></a> Docker tags and versioning</h2><p>The version of Photoview, when running Docker, can be specified using a tag. There exists the following tags:</p><ul><li><code>latest</code>, this is the latest released version.</li><li><code>edge</code>, this reflects the master branch and thus might include unreleased and unfinished features. It is not recommended to use this in production.</li></ul><p>Besides those tags, a particular version can be specified. This is done using the following formatting: <code>x.y.z</code> (eg. <code>2.3.5</code>) or <code>x.y</code> (eg. <code>2.3</code>) or <code>x</code> (eg. <code>2</code>), where:</p><ul><li><code>x</code> is the major version, each major version is not compatiable with the previous.</li><li><code>y</code> is the minor version, each minor version includes bigger features and changes, but it keeps compatibility.</li><li><code>z</code> is the patch version, a patch version only includes bug fixes and minor improvements.</li></ul><p>If a full version is specified, for example <code>2.3.6</code>, then that corresponds with that specific release and that image will never change. But if only <code>2.3</code> that represents the latest patch version for <code>2.3.z</code>, thus if a <code>2.3.7</code> is released, <code>2.3</code> will also be updated. Lastly <code>2</code> would be the latest version within the major version.</p><p>It is recommended to use version <code>2</code> for most circumstances, as in that way you get the latest updates, but your system will not break after an automatic update.</p><h2 id="updating" tabindex="-1"><a class="header-anchor" href="#updating" aria-label="Anchor"></a> Updating</h2><p>To update Photoview running in a docker-compose environment, simply run the following commands:</p><pre class="language-bash"><code class="language-bash">$ docker-compose pull    <span class="token comment"># Pull the latest images</span><br>$ docker-compose up -d   <span class="token comment"># Restart and update the containers whose images has changed</span></code></pre></main></div></div><div id="search-overlay" class="hidden"><div id="search-dimmer" class="fixed top-0 left-0 w-full h-full bg-black opacity-10"></div><div class="fixed top-20 left-1/2 transform -translate-x-1/2 bg-white shadow-lg border border-gray-200 rounded-md p-4 w-40rem overflow-y-auto h-3/4" role="dialog"><input id="search-field" type="search" class="mb-4 w-full py-2 px-3 text-sm border border-gray-200 rounded-md" placeholder="Search" aria-autocomplete="list" autocomplete="off" autocorrect="off" autocapitalize="none" spellcheck="false" enterkeyhint="search" aria-controls="search-results-box"><div role="listbox" aria-label="Search" id="search-results-box" class="">Loading results...</div></div></div><script defer="defer" src="/docs/docs-scripts.js"></script></body></html>