lp-archive

Merge ~ruinedyourlife/lp-archive:feat-landing-page into lp-archive:main

  1. Git
  2. lp:~ruinedyourlife/lp-archive
  3. feat-landing-page
  4. Merge into main
Proposed by Quentin Debhi
Status: Superseded
Proposed branch: ~ruinedyourlife/lp-archive:feat-landing-page
Merge into: lp-archive:main
Diff against target: 166 lines (+132/-3)
3 files modified
lp_archive/__init__.py (+1/-1)
lp_archive/root.py (+2/-2)
lp_archive/templates/index.html (+129/-0)
Reviewer Review Type Date Requested Status
Ines Almeida Approve
Jürgen Gmach Needs Fixing
Review via email: mp+463217@code.launchpad.net

This proposal has been superseded by a proposal from 2024-04-08.

Commit message

Add a landing page

Display a stylized html page with the snapshot documentation

To post a comment you must log in.
Revision history for this message
Jürgen Gmach (jugmac00) wrote :

A screenshot of the landing page would be super helpful when reviewing these changes.

review: Needs Fixing
Revision history for this message
Jürgen Gmach (jugmac00) wrote :

Screenshot see https://chat.canonical.com/canonical/pl/54ni96h66fgixgcrh8773heooh

Revision history for this message
Jürgen Gmach (jugmac00) wrote :

Guruprasad will follow up with Julian about some details, see https://chat.canonical.com/canonical/pl/4ng563xt6tghjpkyrtcbphsqxe

Revision history for this message
Ines Almeida (ines-almeida) wrote :

The page looks great, this is a great improvement! I added a few suggestions.

A bit of a nit, but when `apt` shows up in the text sometimes it's between the `<code>` tags and sometimes not - I would always have it with the `<code>` tag.

review: Needs Fixing
Revision history for this message
Ines Almeida (ines-almeida) wrote :

Left a couple of very minor comments that still need to be addressed, but this looks good to me :thumbs_up:

review: Approve
Revision history for this message
Guruprasad (lgp171188) :
Revision history for this message
Ines Almeida (ines-almeida) wrote (last edit ):

Thinking about this further and after a chat with Aaron, I think we should generally either follow what is in https://docs.google.com/document/d/1loqLRYCZ1CmvK5iVIRunTC947XjlRHkUMnUHGndwqtg more faithfully, or suggest any changes in the document directly, since the contents of that document were reviewed by a few people already and that way they would have a say in any changes.

Happy to go through this with you to decide which changes to suggest, but also happy with whatever you decide (revert any changes to the original, or add the comment in the docs). Sorry for going back on my approval :)

review: Needs Fixing
Revision history for this message
Ines Almeida (ines-almeida) wrote :

Looks good, thank you for making the suggested changes!

review: Approve
Revision history for this message
Otto Co-Pilot (otto-copilot) wrote :

Voting criteria not met.
https://jenkins.ols.ps5.canonical.com/job/lp-archive/30/

Unmerged commits

dddbbeb... by Quentin Debhi

feat: documentation landing page

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1diff --git a/lp_archive/__init__.py b/lp_archive/__init__.py
2index c1ecd4d..0134abd 100644
3--- a/lp_archive/__init__.py
4+++ b/lp_archive/__init__.py
5@@ -22,7 +22,7 @@ ROOT = Path(__file__).parent.parent.resolve()
6
7
8 def create_app(test_config: dict[str, Any] | None = None) -> Flask:
9- app = Flask(__name__, static_folder=None, host_matching=True)
10+ app = Flask(__name__, static_folder=None, template_folder="./templates", host_matching=True)
11 if test_config is None:
12 try:
13 config_text = Path(
14diff --git a/lp_archive/root.py b/lp_archive/root.py
15index f0304b5..e175759 100644
16--- a/lp_archive/root.py
17+++ b/lp_archive/root.py
18@@ -3,11 +3,11 @@
19
20 """API views for the Launchpad archive service."""
21
22-from flask import Flask
23+from flask import Flask, render_template
24
25
26 def root() -> tuple[str, dict[str, str]]:
27- return "Launchpad archive service.\n", {"Content-Type": "text/plain"}
28+ return render_template("index.html"), {"Content-Type": "text/html"}
29
30
31 def init_app(app: Flask) -> None:
32diff --git a/lp_archive/templates/index.html b/lp_archive/templates/index.html
33new file mode 100644
34index 0000000..54f2c32
35--- /dev/null
36+++ b/lp_archive/templates/index.html
37@@ -0,0 +1,129 @@
38+<!DOCTYPE html>
39+<html lang="en">
40+<head>
41+ <meta charset="UTF-8">
42+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
43+ <title>Ubuntu Snapshot Service</title>
44+ <link rel="stylesheet" href="https://assets.ubuntu.com/v1/vanilla-framework-version-4.9.1.min.css" />
45+</head>
46+<body class="is-paper">
47+
48+<div class="p-strip--highlighted">
49+ <div class="row">
50+ <div class="col-12">
51+ <h1 class="p-heading--1">Ubuntu Snapshot Service</h1>
52+ <p>The Ubuntu snapshot service makes it possible to see and use the Ubuntu archive as it was at any specified date and time. Snapshots of the Ubuntu archive are available for any date and time after 1 March 2023. This means that you are able to enable the service on the repositories and use <code>apt</code> to query or install packages as they were at any recent date and time.</p>
53+ <p>Common use cases of this service include:</p>
54+ <ul>
55+ <li>enabling reproducible deployments of a set of packages as at a particular date and time;</li>
56+ <li>determining when a change in behaviour occurred in the archive; and</li>
57+ <li>supporting a structured update workflow, for example where a snapshot is validated in</br>one environment before being released to other environments.</li>
58+ </ul>
59+ <p>Snapshots are supported in Ubuntu 23.10 onwards, plus on updated installations of Ubuntu 20.04 LTS (<code>apt</code> 2.0.10) and Ubuntu 22.04 LTS (<code>apt</code> 2.4.11). We intend to ensure snapshots are available for dates up to at least 2 years in the past, which we may extend if there is demand.</p>
60+ </div>
61+ </div>
62+</div>
63+
64+<div class="p-strip">
65+ <div class="row">
66+ <div class="col-12">
67+ <h2 id="quick-start-example">Quick-start Example</h2>
68+ <p>On Ubuntu 24.04 LTS and later have installing the version of <code>hello</code> as it was at 3:04:00 am UTC on 1 March 2024 is as simple as using the following command (on an instance that does not already have hello installed):</p>
69+ <pre><code>apt install hello --update --snapshot 20240301T030400Z</code></pre>
70+ <p>This command first updates your package indexes (the <code>--update</code> argument is the equivalent of running <code>apt</code> update before the specified <code>apt</code> command) and then installs the hello package from the specified snapshot instead of the latest version in the archive. In the output you should see that the package is being downloaded from the snapshot server:</p>
71+ <pre><code>Get:1 https://snapshot.ubuntu.com/ubuntu/20240301T030400Z noble/main
72+amd64 hello amd64 2.10-3 [26.2 kB]</code></pre>
73+ </div>
74+ </div>
75+</div>
76+
77+<div class="p-strip--highlighted">
78+ <div class="row">
79+ <div class="col-12">
80+ <h2>How to Use Snapshots on Ubuntu</h2>
81+ <h3 class="u-sv3">Enable Snapshot Service</h3>
82+ <h4>For Ubuntu 24.04 and later</h4>
83+ <p>The <code>apt</code> included in Ubuntu 24.04 and later automatically detects when snapshots are supported for a repository (any repository with a Snapshots: directive in the Release file). This includes the official Ubuntu repositories, so snapshots for these will be enabled by default.</p>
84+
85+ <h4>For Ubuntu 23.10 and later</h4>
86+ <p>On Ubuntu 23.10 and earlier, edit <code>/etc/apt/sources.list</code> to add <code>[snapshot=yes]</code> into the standard prefix, for example:</p>
87+ <pre><code>deb [snapshot=yes] http://archive.ubuntu.com/ubuntu/ jammy main restricted
88+deb [snapshot=yes] http://archive.ubuntu.com/ubuntu/ jammy-updates main restricted
89+deb [snapshot=yes] http://security.ubuntu.com/ubuntu jammy-security main restricted</code></pre>
90+
91+ <h3 class="u-sv3">Use a Snapshot ID with apt Commands</h3>
92+ <h4>Snapshot ID format</h4>
93+ <p>The Snapshot ID will be the desired date and UTC time in the YYYYMMDDTHHMMSSZ format, for example 20230302T030400Z for 03:04 UTC on 2 March 2023.</p>
94+
95+ <h4>Using a Snapshot ID with each apt command</h4>
96+ <p>Once snapshots are enabled for a repository, it is possible to pass a specific Snapshot ID to most <code>apt</code> or <code>apt-get</code> commands with <code>--snapshot [Snapshot ID]</code> or <code>-S [Snapshot ID]</code>, for example:</p>
97+ <pre><code>apt update --snapshot 20231102T030400Z
98+apt policy hello -S 20231102T030400Z
99+apt install hello --snapshot 20231102T030400Z</code></pre>
100+ <p>Note that the <code>apt update --snapshot [snapshot]</code> command needs to be run immediately before the other <code>apt</code> commands. These commands will also fail if the snapshot format is incorrect or the snapshot does not exist (for example, if you try to use a date before that Ubuntu release existed).</p>
101+
102+ <h4>Using a specifig Snapshot ID for all apt commands</h4>
103+ <p>Enabling snapshots for the repository will allow you to specify a snapshot when using <code>apt</code>, as shown above. Alternatively, it is possible to set <code>apt</code> to use a particular snapshot for all <code>apt</code> commands. To do this, the specific Snapshot ID (e.g. 20230302T030400Z) can be used in the place of “yes” in the relevant source. If a specific snapshot is configured in this way then it will be used even if a different snapshot ID is given as part of an <code>apt</code> command.</p>
104+ <p>For example, on Ubuntu 24.04 LTS onwards:</p>
105+ <pre><code>Types: deb
106+URIs: http://archive.ubuntu.com/ubuntu
107+Suites: noble noble-updates
108+Components: main universe
109+Signed-By: /usr/share/keyrings/ubuntu-archive-keyring.gpg
110+Snapshot: 20240301T030400Z
111+
112+Ubuntu security updates. Aside from URIs and Suites,
113+## this should mirror your choices in the previous section.
114+Types: deb
115+URIs: http://security.ubuntu.com/ubuntu
116+Suites: noble-security
117+Components: main universe
118+Signed-By: /usr/share/keyrings/ubuntu-archive-keyring.gpg
119+Snapshot: 20240301T030400Z</code></pre>
120+ <p>Ubuntu 23.10 and earlier:</p>
121+ <pre><code>deb [snapshot=20230302T030400Z] http://archive.ubuntu.com/ubuntu/ jammy main restricted
122+deb [snapshot=20230302T030400Z] http://archive.ubuntu.com/ubuntu/ jammy-updates main restricted
123+deb [snapshot=20230302T030400Z] http://security.ubuntu.com/ubuntu jammy-security main restricted</code></pre>
124+
125+ <h3>Disable Snapshot Service</h3>
126+ <h4>For Ubuntu 24.04 and later (Deb822 sources)</h4>
127+ <p>As mentioned above, on Ubuntu 24.04 and later, snapshots are enabled automatically for supported repositories. If you do <b>not</b> want archive snapshots to be enabled for a repository, edit the relevant sources file (e.g. <code>/etc/apt/sources.list.d/ubuntu.sources</code>) to add <code>Snapshot: no</code> to the relevant sources, for example:</p>
128+ <pre><code>Types: deb
129+URIs: http://archive.ubuntu.com/ubuntu
130+Suites: noble noble-updates
131+Components: main universe
132+Signed-By: /usr/share/keyrings/ubuntu-archive-keyring.gpg
133+Snapshot: no</code></pre>
134+
135+ <h4>For Ubuntu 23.10 and earlier</h4>
136+ <p>On Ubuntu 23.10 and earlier the included version of <code>apt</code> did not automatically detect snapshot support and so snapshots should not be enabled unless you have added <code>[snapshot=yes]</code> to the relevant source (as explained above).</p>
137+ </div>
138+ </div>
139+</div>
140+
141+<div class="p-strip">
142+ <div class="row">
143+ <div class="col-12">
144+ <h2>See Also</h2>
145+ <ul class="p-list">
146+ <li><a href="https://www.youtube.com/watch?v=0tAzyHsNi3s">APT Archive Snapshot Integration Demo (Ubuntu 23.10)</a></li>
147+ <li><a href="https://ubuntu.com/blog/ubuntu-snapshots-on-azure-ensuring-predictability-and-consistency-in-cloud-deployments">Ubuntu Snapshots on Microsoft Azure: Ensuring predictability and consistency in cloud deployments</a></li>
148+ <li><a href="https://ubuntu.com/blog/securing-multiple-ubuntu-instances-while-maximising-uptime">Ubuntu Explained: How to ensure security and stability in cloud instances—part 3</a></li>
149+ <li><a href="https://manpages.ubuntu.com/manpages/noble/en/man8/apt-get.8.html">apt-get manpage</a></li>
150+ <li><a href="https://manpages.ubuntu.com/manpages/noble/en/man5/apt.conf.5.html">apt.conf manpage</a></li>
151+ <li><a href="https://manpages.ubuntu.com/manpages/noble/en/man5/sources.list.5.html">sources.list manpage</a></li>
152+ <li><a href="https://techcommunity.microsoft.com/t5/linux-and-open-source-blog/increased-security-and-resiliency-of-canonical-workloads-on/ba-p/3970623">Increased security and resiliency of Canonical workloads on Azure - now in preview</a></li>
153+ <li><a href="https://www.youtube.com/watch?v=hxDPqRDY5Lk">Using Ubuntu’s new snapshot service at scale with Azure and AKS</a></li>
154+ </ul>
155+ </div>
156+ </div>
157+</div>
158+
159+<footer class="p-strip is-shallow">
160+ <div class="row">
161+ <p class="u-align-text--center">© 2024 <a href="http://canonical.com/">Canonical&nbsp;Ltd.</a></p>
162+ </div>
163+</footer>
164+
165+</body>
166+</html>

Subscribers

People subscribed via source and target branches