mirror of
https://github.com/certbot/certbot.git
synced 2026-01-26 07:41:33 +03:00
Simplify/document snap creation (#8404)
This PR adds the following documentation improvements to fix https://github.com/certbot/certbot/issues/7958: - Simplify building external plugins - Separate out certbot snap instructions from plugin instructions - Mention that dnsimple is just an example for the plugin instructions - Mention remote build for other architectures - Mention snap doc exists elsewhere in developer guide (`contributing.rst`) * Set up generate_dnsplugins_all.sh for all files and parametrize snapcraft and postrefreshhook files * Create constraints file in the generate_dnsplugins_all script * Separate out plugin and certbot snaps and update instructions * Add remote build instructions * Add pointers to the README to contributing.rst
This commit is contained in:
ohemorange
GitHub
@@ -375,6 +375,9 @@ The script used to generate the snapcraft.yaml files for our own externally
|
||||
snapped plugins can be found at
|
||||
https://github.com/certbot/certbot/blob/master/tools/snap/generate_dnsplugins_snapcraft.sh.
|
||||
|
||||
For more information on building externally snapped plugins, see the section on
|
||||
:ref:`Building snaps`.
|
||||
|
||||
Once you have created your own snap, if you have the snap file locally,
|
||||
it can be installed for use with Certbot by running:
|
||||
|
||||
@@ -534,6 +537,15 @@ Use of EFFOSCCP is subject to the `EFF Code of Conduct
|
||||
<https://www.eff.org/pages/eppcode>`_. When investigating an alleged Code of
|
||||
Conduct violation, EFF may review discussion channels or direct messages.
|
||||
|
||||
.. _Building snaps:
|
||||
|
||||
Building the Certbot and DNS plugin snaps
|
||||
=========================================
|
||||
|
||||
Instructions for how to manually build and run the Certbot snap and the externally
|
||||
snapped DNS plugins that the Certbot project supplies are located in the README
|
||||
file at https://github.com/certbot/certbot/tree/master/tools/snap.
|
||||
|
||||
Updating certbot-auto and letsencrypt-auto
|
||||
==========================================
|
||||
|
||||
|
||||
@@ -1,7 +1,10 @@
|
||||
# Certbot Snaps
|
||||
# Building Certbot Snaps
|
||||
|
||||
## Local Testing and Development
|
||||
|
||||
These instructions are recommended when testing anything about the snap setup for ease of debugging.
|
||||
The architecture of the built snap is limited to the architecture of the system it is built on.
|
||||
|
||||
### Initial VM Set Up
|
||||
|
||||
These steps need to be done once to set up your VM and do not need to be run again to rebuild the snap.
|
||||
@@ -15,31 +18,83 @@ These steps need to be done once to set up your VM and do not need to be run aga
|
||||
6. Install snapcraft with `sudo snap install --classic snapcraft`.
|
||||
7. `cd ~` (or any other directory where you want our source files to be)
|
||||
8. Run `git clone git://github.com/certbot/certbot`
|
||||
9. `cd certbot`
|
||||
9. `cd certbot` (All further instructions are relative to this directory.)
|
||||
|
||||
### Build the Snaps
|
||||
### Certbot Snap
|
||||
|
||||
These are the steps to build and install the snaps. If you have run these steps before, you may want to run the commands in the section below to clean things up before building the snap again.
|
||||
#### Reset the Environment
|
||||
|
||||
If the snap has been built before, the instructions below clean up the build environment so it can reliably be used again.
|
||||
|
||||
1. `snapcraft clean --use-lxd`
|
||||
2. [Optional] `mv certbot_*_amd64.snap certbot_amd64.snap.bak`
|
||||
|
||||
#### Build the Certbot Snap
|
||||
|
||||
These are the steps to build and install the Certbot snap. If you have run these steps before, you may want to run the commands in the section above to clean things up or save a previous build before building the snap again (running `snapcraft` again will overwrite the previous snap).
|
||||
|
||||
1. Run `snapcraft --use-lxd`.
|
||||
2. Install the generated snap with `sudo snap install --dangerous --classic certbot_*_amd64.snap`. You can transfer the snap to a different machine to run it there instead if you prefer.
|
||||
3. Run `tools/merge_requirements.py tools/dev_constraints.txt <(tools/strip_hashes.py letsencrypt-auto-source/pieces/dependency-requirements.txt) > certbot-dns-dnsimple/snap-constraints.txt` (this is a workaround for https://github.com/certbot/certbot/issues/8100).
|
||||
4. `cd certbot-dns-dnsimple`
|
||||
5. `snapcraft --use-lxd`
|
||||
6. Run `sudo snap set certbot trust-plugin-with-root=ok`.
|
||||
7. Install the generated snap with `sudo snap install --dangerous certbot-dns-dnsimple_*_amd64.snap`. Again, you can transfer the snap to a different machine to run it there instead if you prefer.
|
||||
8. Connect the plugin with `sudo snap connect certbot:plugin certbot-dns-dnsimple`.
|
||||
9. Connect the plugin metadata with `sudo snap connect certbot-dns-dnsimple:certbot-metadata certbot:certbot-metadata`. Install the plugin again to test refresh; logs are at `/var/snap/certbot-dns-dnsimple/current/debuglog`.
|
||||
10. Now you can run Certbot as normal. For example, `certbot plugins` should display the DNSimple plugin as installed.
|
||||
|
||||
### Reset the Environment
|
||||
#### Run
|
||||
|
||||
The instructions below clean up the build environment so it can reliably be used again.
|
||||
Run Certbot as normal. For example, `certbot plugins` should display the Apache and Nginx plugins.
|
||||
|
||||
1. `cd ~/certbot` (or to an alternate path where you put our source files)
|
||||
2. `snapcraft clean --use-lxd`
|
||||
3. `rm certbot_*_amd64.snap`
|
||||
4. `cd certbot-dns-dnsimple`
|
||||
5. `rm certbot-dns-dnsimple_*_amd64.snap`
|
||||
6. `snapcraft clean --use-lxd`
|
||||
7. `cd ..`
|
||||
### Certbot Plugin Snaps
|
||||
|
||||
These instructions use the `certbot-dns-dnsimple` plugin as an example, but all of Certbot's other plugin snaps can be built in the same way.
|
||||
|
||||
#### Reset the Environment
|
||||
|
||||
If the plugin snap has been built before, the instructions below clean up the build environment so it can reliably be used again.
|
||||
|
||||
1. `cd certbot-dns-dnsimple`
|
||||
2. `snapcraft clean --use-lxd`
|
||||
3. [Optional] `mv certbot-dns-dnsimple_*_amd64.snap certbot-dns-simple_amd64.snap.bak`
|
||||
4. `cd ..`
|
||||
|
||||
#### Build a Certbot Plugin Snap
|
||||
|
||||
These are the steps to build and install the Certbot DNSimple plugin snap. If you have run these steps before, you may want to run the commands in the section above to clean things up or save a previous build before building the snap again (running `snapcraft` again will overwrite the previous snap).
|
||||
|
||||
1. Run `tools/snap/generate_dnsplugins_all.sh` to generate all necessary files for all plugin snaps.
|
||||
2. `cd certbot-dns-dnsimple`
|
||||
3. `snapcraft --use-lxd`
|
||||
4. Run `sudo snap set certbot trust-plugin-with-root=ok`.
|
||||
5. Install the generated snap with `sudo snap install --dangerous certbot-dns-dnsimple_*_amd64.snap`. Again, you can transfer the snap to a different machine to run it there instead if you prefer.
|
||||
6. Connect the plugin with `sudo snap connect certbot:plugin certbot-dns-dnsimple`.
|
||||
7. Connect the plugin metadata with `sudo snap connect certbot-dns-dnsimple:certbot-metadata certbot:certbot-metadata`. Install the plugin again to test refresh; logs are at `/var/snap/certbot-dns-dnsimple/current/debuglog`.
|
||||
|
||||
#### Run
|
||||
|
||||
Run Certbot as normal. For example, `certbot plugins` should display the DNSimple plugin as installed.
|
||||
|
||||
## Building for Other Architectures
|
||||
|
||||
To build for an unavailable architecture or for multiple architectures simultaneously, we recommend using snapcraft's remote build feature.
|
||||
It is easiest to run this from a local machine.
|
||||
|
||||
### Initial Local Setup
|
||||
|
||||
1. Create or log into an Ubuntu One account [here](https://login.launchpad.net/).
|
||||
2. Install git and python with `sudo apt update && sudo apt install -y git python`.
|
||||
3. Install snapcraft with `sudo snap install --classic snapcraft`.
|
||||
4. `cd ~` (or any other directory where you want our source files to be)
|
||||
5. Run `git clone git://github.com/certbot/certbot`
|
||||
6. `cd certbot` (All further instructions are relative to this directory.)
|
||||
7. To trigger `snapcraft` to request access to your Launchpad account, run
|
||||
`snapcraft remote-build --launchpad-accept-public-upload --status`. A URL where you need
|
||||
to grant this access will be printed to your terminal and automatically open in your browser
|
||||
if one is available.
|
||||
|
||||
### Build Snaps Remotely
|
||||
|
||||
Certbot provides a wrapper around snapcraft's remote build to make building all of our plugins easier. To see all available
|
||||
options, run `python3 tools/snap/build_remote.py --help`.
|
||||
|
||||
For example, to build all available snaps for all architectures, run `python3 tools/snap/build_remote.py ALL --archs amd64 arm64 armhf`.
|
||||
|
||||
To build only the certbot snap on only amd64, run `python3 tools/snap/build_remote.py certbot --archs armhf`.
|
||||
|
||||
The command will upload the entire contents of the working directory, so if the remote build
|
||||
appears to hang, try using a clean clone of the `certbot` repository.
|
||||
|
||||
15
tools/snap/generate_dnsplugins_all.sh
Executable file
15
tools/snap/generate_dnsplugins_all.sh
Executable file
@@ -0,0 +1,15 @@
|
||||
#!/bin/bash
|
||||
# Generate all necessary files for building snaps for all DNS plugins
|
||||
set -eu
|
||||
|
||||
DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
|
||||
CERTBOT_DIR="$(dirname "$(dirname "${DIR}")")"
|
||||
|
||||
for PLUGIN_PATH in "${CERTBOT_DIR}"/certbot-dns-*; do
|
||||
bash "${CERTBOT_DIR}"/tools/snap/generate_dnsplugins_snapcraft.sh $PLUGIN_PATH
|
||||
bash "${CERTBOT_DIR}"/tools/snap/generate_dnsplugins_postrefreshhook.sh $PLUGIN_PATH
|
||||
# Create constraints file
|
||||
"${CERTBOT_DIR}"/tools/merge_requirements.py tools/dev_constraints.txt \
|
||||
<("${CERTBOT_DIR}"/tools/strip_hashes.py letsencrypt-auto-source/pieces/dependency-requirements.txt) \
|
||||
> "${PLUGIN_PATH}"/snap-constraints.txt
|
||||
done
|
||||
@@ -1,13 +1,13 @@
|
||||
#!/bin/bash
|
||||
# Generate the hooks/post-refresh file for all DNS plugins
|
||||
# Generate the hooks/post-refresh file for a DNS plugin
|
||||
# Usage: bash generate_dnsplugins_postrefreshhook.sh path/to/dns/plugin
|
||||
# For example, from the certbot home directory:
|
||||
# tools/snap/generate_dnsplugins_postrefreshhook.sh certbot-dns-dnsimple
|
||||
set -eu
|
||||
|
||||
DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
|
||||
CERTBOT_DIR="$(dirname "$(dirname "${DIR}")")"
|
||||
|
||||
for PLUGIN_PATH in "${CERTBOT_DIR}"/certbot-dns-*; do
|
||||
mkdir -p "${PLUGIN_PATH}/snap/hooks"
|
||||
cat <<EOF > "${PLUGIN_PATH}/snap/hooks/post-refresh"
|
||||
PLUGIN_PATH=$1
|
||||
mkdir -p "${PLUGIN_PATH}/snap/hooks"
|
||||
cat <<EOF > "${PLUGIN_PATH}/snap/hooks/post-refresh"
|
||||
#!/bin/sh -e
|
||||
# This file is generated by tools/generate_dnsplugins_postrefreshhook.sh and should not be edited manually.
|
||||
|
||||
@@ -31,4 +31,3 @@ if [ "\$exit_code" -eq 1 ]; then
|
||||
exit 1
|
||||
fi
|
||||
EOF
|
||||
done
|
||||
|
||||
@@ -1,15 +1,15 @@
|
||||
#!/bin/bash
|
||||
# Generate the snapcraft.yaml file for all DNS plugins
|
||||
# Generate the snapcraft.yaml file for a DNS plugins
|
||||
# Usage: bash generate_dnsplugins_snapcraft.sh path/to/dns/plugin
|
||||
# For example, from the certbot home directory:
|
||||
# tools/snap/generate_dnsplugins_snapcraft.sh certbot-dns-dnsimple
|
||||
set -e
|
||||
|
||||
DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
|
||||
CERTBOT_DIR="$(dirname "$(dirname "${DIR}")")"
|
||||
|
||||
for PLUGIN_PATH in "${CERTBOT_DIR}"/certbot-dns-*; do
|
||||
PLUGIN=$(basename "${PLUGIN_PATH}")
|
||||
DESCRIPTION=$(grep description "${PLUGIN_PATH}/setup.py" | sed -E 's|\s+description="(.*)",|\1|g')
|
||||
mkdir -p "${PLUGIN_PATH}/snap"
|
||||
cat <<EOF > "${PLUGIN_PATH}/snap/snapcraft.yaml"
|
||||
PLUGIN_PATH=$1
|
||||
PLUGIN=$(basename "${PLUGIN_PATH}")
|
||||
DESCRIPTION=$(grep description "${PLUGIN_PATH}/setup.py" | sed -E 's|\s+description="(.*)",|\1|g')
|
||||
mkdir -p "${PLUGIN_PATH}/snap"
|
||||
cat <<EOF > "${PLUGIN_PATH}/snap/snapcraft.yaml"
|
||||
# This file is generated by tools/generate_dnsplugins_snapcraft.sh and should not be edited manually.
|
||||
name: ${PLUGIN}
|
||||
summary: ${DESCRIPTION}
|
||||
@@ -52,4 +52,3 @@ plugs:
|
||||
content: metadata-1
|
||||
target: \$SNAP/certbot-shared
|
||||
EOF
|
||||
done
|
||||
|
||||
Reference in New Issue
Block a user