canonical · tigarmo · Mar 6, 2025 · Mar 3, 2025 · Mar 3, 2025 · Mar 3, 2025
@@ -0,0 +1,29 @@
+###########################################
+# IMPORTANT
+# Comments matter!
+# The docs use the wrapping comments as
+# markers for including said instructions
+# as snippets in the docs.
+###########################################
+summary: common setup instructions
+
+execute: |
+  date
+  # [docs:install-rockcraft]
+  sudo snap install rockcraft --classic --channel latest/edge
+  # [docs:install-rockcraft-end]
+
+  # [docs:install-docker]
+  sudo snap install docker
+  # [docs:install-docker-end]
+
+  # [docs:docker-regular-user]
+  sudo addgroup --system docker
+  sudo adduser $USER docker
+  newgrp docker
+  # [docs:docker-regular-user-end]
+
+  # [docs:docker-enable]
+  sudo snap disable docker
+  sudo snap enable docker
+  # [docs:docker-enable-end]
@@ -21,6 +21,9 @@ execute: |
   sudo addgroup --system docker
   sudo adduser $USER docker
   newgrp docker
+  # [docs:docker-regular-user-end]
+
+  # [docs:docker-enable]
   sudo snap disable docker
   sudo snap enable docker
-  # [docs:docker-regular-user-end]
+  # [docs:docker-enable-end]
@@ -0,0 +1,103 @@
+We recommend starting from a clean Ubuntu installation. If we don't have
+one available, we can create one using `Multipass`_:
+
+.. tabs::
+
+    .. tab:: Ubuntu
+
+        Is Multipass_ already installed and active? Check by running
+
+        .. code-block:: bash
+
+            snap services multipass
+
+        If we see the ``multipass`` service but it isn't "active", then we'll
+        need to run ``sudo snap start multipass``. On the other hand, if we get
+        an error saying ``snap "multipass" not found``, then we must install
+        `Multipass <install-multipass_>`_:
+
+        .. code-block:: bash
+
+            sudo snap install multipass
+
+    .. tab:: Windows
+
+        See `Multipass installation instructions <install-multipass_>`_, switch
+        to Windows in the drop down.
+
+    .. tab:: macOS
+
+        See `Multipass installation instructions <install-multipass_>`_, switch
+        to macOS in the drop down.
+
+Then we can create the VM with the following command:
+
+.. code-block:: text
+
+    multipass launch --disk 10G --name rock-dev 24.04
+
+Finally, once the VM is up, open a shell into it:
+
+.. code-block:: bash
+
+    multipass shell rock-dev
+
+----
+
+`LXD`_ will be required for building the rock. Make sure it is installed
+and initialised:
+
+.. code-block:: bash
+
+   sudo snap install lxd
+   lxd init --auto
+
+In order to create the rock, we'll need to install Rockcraft:
+
+.. literalinclude:: /reuse/tutorial/code/edge/task.yaml
+    :language: bash
+    :start-after: [docs:install-rockcraft]
+    :end-before: [docs:install-rockcraft-end]
+    :dedent: 2
+
+This tutorial requires the ``latest/edge`` channel of Rockcraft as the
+framework is currently experimental.
+
+We'll use Docker to run the rock. We can install it as a ``snap``:
+
+.. literalinclude:: /reuse/tutorial/code/edge/task.yaml
+    :language: bash
+    :start-after: [docs:install-docker]
+    :end-before: [docs:install-docker-end]
+    :dedent: 2
+
+By default, Docker is only accessible with root privileges (``sudo``). We want
+to be able to use Docker commands as a regular user:
+
+.. literalinclude:: /reuse/tutorial/code/edge/task.yaml
+    :language: bash
+    :start-after: [docs:docker-regular-user]
+    :end-before: [docs:docker-regular-user-end]
+    :dedent: 2
+
+Restart Docker:
+
+.. literalinclude:: /reuse/tutorial/code/stable/task.yaml
+    :language: bash
+    :start-after: [docs:docker-enable]
+    :end-before: [docs:docker-enable-end]
+    :dedent: 2
+
+.. warning::
+   There is a `known connectivity issue with LXD and Docker
+   <lxd-docker-connectivity-issue_>`_. If we see a
+   networking issue such as "*A network related operation failed in a context
+   of no network access*", make sure to apply one of the suggested fixes
+   `here <lxd-docker-connectivity-issue_>`_.
+
+Note that we'll also need a text editor. We can either install one of our
+choice or simply use one of the already existing editors in the Ubuntu
+environment (like ``vi``).
+
+.. _`lxd-docker-connectivity-issue`: https://documentation.ubuntu.com/lxd/en/latest/howto/network_bridge_firewalld/#prevent-connectivity-issues-with-lxd-and-docker
+.. _`install-multipass`: https://multipass.run/docs/install-multipass
@@ -54,15 +54,15 @@ and initialised:
 
 In order to create the rock, we'll need to install Rockcraft:
 
-.. literalinclude:: /reuse/tutorial/code/task.yaml
+.. literalinclude:: /reuse/tutorial/code/stable/task.yaml
     :language: bash
     :start-after: [docs:install-rockcraft]
     :end-before: [docs:install-rockcraft-end]
     :dedent: 2
 
 We'll use Docker to run the rock. We can install it as a ``snap``:
 
-.. literalinclude:: /reuse/tutorial/code/task.yaml
+.. literalinclude:: /reuse/tutorial/code/stable/task.yaml
     :language: bash
     :start-after: [docs:install-docker]
     :end-before: [docs:install-docker-end]
@@ -71,12 +71,20 @@ We'll use Docker to run the rock. We can install it as a ``snap``:
 By default, Docker is only accessible with root privileges (``sudo``). We want
 to be able to use Docker commands as a regular user:
 
-.. literalinclude:: /reuse/tutorial/code/task.yaml
+.. literalinclude:: /reuse/tutorial/code/stable/task.yaml
     :language: bash
     :start-after: [docs:docker-regular-user]
     :end-before: [docs:docker-regular-user-end]
     :dedent: 2
 
+Restart Docker:
+
+.. literalinclude:: /reuse/tutorial/code/stable/task.yaml
+    :language: bash
+    :start-after: [docs:docker-enable]
+    :end-before: [docs:docker-enable-end]
+    :dedent: 2
+
 .. warning::
    There is a `known connectivity issue with LXD and Docker
    <lxd-docker-connectivity-issue_>`_. If we see a

@@ -8,7 +8,7 @@ in :doc:`/tutorial/hello-world`.
 Setup your environment
 ----------------------
 
-.. include:: /reuse/tutorial/setup.rst
+.. include:: /reuse/tutorial/setup_stable.rst
 
 Project setup
 -------------

@@ -10,7 +10,7 @@ containerise it in a rock, using Rockcraft's ``django-framework``
 Setup
 =====
 
-.. include:: /reuse/tutorial/setup.rst
+.. include:: /reuse/tutorial/setup_stable.rst
 
 Finally, create a new directory for this tutorial and go inside it:
 

@@ -10,11 +10,7 @@ containerise it in a rock with Rockcraft's
 Setup
 =====
 
-.. include:: /reuse/tutorial/setup.rst
-
-Before we go any further, for this tutorial we'll need the most recent version
-of Rockcraft on the edge channel. Run ``sudo snap refresh rockcraft --channel
-latest/edge`` to switch to it.
+.. include:: /reuse/tutorial/setup_edge.rst
 
 Finally, create a new directory for this tutorial and go inside it:
 

@@ -10,14 +10,7 @@ containerise it in a rock, using Rockcraft's ``flask-framework``
 Setup
 =====
 
-.. include:: /reuse/tutorial/setup.rst
-
-.. note::
-    This tutorial requires version ``1.5.2`` or later for Rockcraft. Check
-    the version using ``rockcraft --version``. If there's an older version
-    of Rockcraft installed, use
-    ``sudo snap refresh rockcraft --channel latest/stable`` to get the latest
-    stable version.
+.. include:: /reuse/tutorial/setup_stable.rst
 
 Finally, create a new directory for this tutorial and go inside it:
 

@@ -20,11 +20,7 @@ rocks for Go applications.
 Setup
 =====
 
-.. include:: /reuse/tutorial/setup.rst
-
-This tutorial requires the ``latest/edge`` channel of Rockcraft. Run
-``sudo snap refresh rockcraft --channel latest/edge`` to get the latest
-edge version.
+.. include:: /reuse/tutorial/setup_edge.rst
 
 In order to test the Go application locally, before packing it into a rock,
 install ``go``.

@@ -4,7 +4,7 @@ Create a "Hello World" rock
 Setup your environment
 ----------------------
 
-.. include:: /reuse/tutorial/setup.rst
+.. include:: /reuse/tutorial/setup_stable.rst
 
 Project setup
 -------------

@@ -9,7 +9,7 @@ into a rock.
 Setup your environment
 ----------------------
 
-.. include:: /reuse/tutorial/setup.rst
+.. include:: /reuse/tutorial/setup_stable.rst
 
 Project setup
 -------------

@@ -16,7 +16,7 @@ By the end of this tutorial you will be able to run pyfiglet via docker:
 Setup your environment
 ----------------------
 
-.. include:: /reuse/tutorial/setup.rst
+.. include:: /reuse/tutorial/setup_stable.rst
 
 Project setup
 -------------
-Original file line number
+Diff line change
@@ Expand Up @@
     Setup
     =====
-    .. include:: /reuse/tutorial/setup.rst
+    .. include:: /reuse/tutorial/setup_stable.rst
     Finally, create a new directory for this tutorial and go inside it:
@@ Expand Down @@