-
Notifications
You must be signed in to change notification settings - Fork 479
/
index.html
14 lines (12 loc) · 19.6 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
<!DOCTYPE html>
<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>SSH Deploy Keys Walkthrough · Documenter.jl</title><meta name="title" content="SSH Deploy Keys Walkthrough · Documenter.jl"/><meta property="og:title" content="SSH Deploy Keys Walkthrough · Documenter.jl"/><meta property="twitter:title" content="SSH Deploy Keys Walkthrough · Documenter.jl"/><meta name="description" content="Documentation for Documenter.jl."/><meta property="og:description" content="Documentation for Documenter.jl."/><meta property="twitter:description" content="Documentation for Documenter.jl."/><meta property="og:url" content="https://documenter.juliadocs.org/stable/man/hosting/walkthrough/"/><meta property="twitter:url" content="https://documenter.juliadocs.org/stable/man/hosting/walkthrough/"/><link rel="canonical" href="https://documenter.juliadocs.org/stable/man/hosting/walkthrough/"/><meta property="og:image" content="https://documenter.juliadocs.org/stable/assets/preview.png"/><meta property="twitter:image" content="https://documenter.juliadocs.org/stable/assets/preview.png"/><meta property="twitter:card" content="summary_large_image"/><script async src="https://www.googletagmanager.com/gtag/js?id=UA-136089579-2"></script><script> window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', 'UA-136089579-2', {'page_path': location.pathname + location.search + location.hash});
</script><script data-outdated-warner src="../../../assets/warner.js"></script><link href="https://cdnjs.cloudflare.com/ajax/libs/lato-font/3.0.0/css/lato-font.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/juliamono/0.050/juliamono.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.2/css/fontawesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.2/css/solid.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.2/css/brands.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.8/katex.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL="../../.."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js" data-main="../../../assets/documenter.js"></script><script src="../../../search_index.js"></script><script src="../../../siteinfo.js"></script><script src="../../../../versions.js"></script><link class="docs-theme-link" rel="stylesheet" type="text/css" href="../../../assets/themes/documenter-dark.css" data-theme-name="documenter-dark" data-theme-primary-dark/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="../../../assets/themes/documenter-light.css" data-theme-name="documenter-light" data-theme-primary/><script src="../../../assets/themeswap.js"></script><link href="../../../assets/favicon.ico" rel="icon" type="image/x-icon"/></head><body><div id="documenter"><nav class="docs-sidebar"><a class="docs-logo" href="../../../"><img class="docs-light-only" src="../../../assets/logo.svg" alt="Documenter.jl logo"/><img class="docs-dark-only" src="../../../assets/logo-dark.svg" alt="Documenter.jl logo"/></a><div class="docs-package-name"><span class="docs-autofit"><a href="../../../">Documenter.jl</a></span></div><button class="docs-search-query input is-rounded is-small is-clickable my-2 mx-auto py-1 px-2" id="documenter-search-query">Search docs (Ctrl + /)</button><ul class="docs-menu"><li><a class="tocitem" href="../../../">Home</a></li><li><span class="tocitem">Manual</span><ul><li><a class="tocitem" href="../../guide/">Guide</a></li><li><a class="tocitem" href="../../examples/">Examples</a></li><li><a class="tocitem" href="../../syntax/">Syntax</a></li><li><a class="tocitem" href="../../doctests/">Doctests</a></li><li><a class="tocitem" href="../../latex/"><span>$\LaTeX$</span> Syntax</a></li><li><input class="collapse-toggle" id="menuitem-2-6" type="checkbox" checked/><label class="tocitem" for="menuitem-2-6"><span class="docs-label">Hosting Documentation</span><i class="docs-chevron"></i></label><ul class="collapsed"><li class="is-active"><a class="tocitem" href>SSH Deploy Keys Walkthrough</a><ul class="internal"><li><a class="tocitem" href="#Generating-an-SSH-Key"><span>Generating an SSH Key</span></a></li><li><a class="tocitem" href="#Adding-the-Public-Key-to-GitHub-or-Gitea-such-as-Codeberg"><span>Adding the Public Key to GitHub or Gitea such as Codeberg</span></a></li><li><a class="tocitem" href="#Adding-the-Private-Key"><span>Adding the Private Key</span></a></li></ul></li></ul></li><li><a class="tocitem" href="../../other-formats/">Other Output Formats</a></li></ul></li><li><a class="tocitem" href="../../../showcase/">Showcase</a></li><li><span class="tocitem">Reference</span><ul><li><a class="tocitem" href="../../../lib/public/">Public API</a></li><li><a class="tocitem" href="../../../lib/remote-links/">Remote repository links</a></li><li><a class="tocitem" href="../../../lib/semver/">Semantic versioning</a></li></ul></li><li><span class="tocitem">Developers</span><ul><li><a class="tocitem" href="../../../contributing/">Contributing</a></li><li><a class="tocitem" href="../../../checklists/">Checklists</a></li><li><input class="collapse-toggle" id="menuitem-5-3" type="checkbox"/><label class="tocitem" for="menuitem-5-3"><span class="docs-label">Internals</span><i class="docs-chevron"></i></label><ul class="collapsed"><li><a class="tocitem" href="../../../lib/internals/anchors/">Anchors</a></li><li><a class="tocitem" href="../../../lib/internals/builder/">Builder</a></li><li><a class="tocitem" href="../../../lib/internals/crossref/">Crossrefs</a></li><li><a class="tocitem" href="../../../lib/internals/deploydocs/">Deploydocs</a></li><li><a class="tocitem" href="../../../lib/internals/docchecks/">DocChecks</a></li><li><a class="tocitem" href="../../../lib/internals/docmeta/">DocMeta</a></li><li><a class="tocitem" href="../../../lib/internals/docsystem/">DocSystem</a></li><li><a class="tocitem" href="../../../lib/internals/doctests/">DocTests</a></li><li><a class="tocitem" href="../../../lib/internals/documentertools/">DocumenterTools</a></li><li><a class="tocitem" href="../../../lib/internals/documents/">Documents</a></li><li><a class="tocitem" href="../../../lib/internals/dom/">DOM</a></li><li><a class="tocitem" href="../../../lib/internals/expanders/">Expanders</a></li><li><a class="tocitem" href="../../../lib/internals/jsdependencies/">JSDependencies</a></li><li><a class="tocitem" href="../../../lib/internals/mdflatten/">MDFlatten</a></li><li><a class="tocitem" href="../../../lib/internals/selectors/">Selectors</a></li><li><a class="tocitem" href="../../../lib/internals/textdiff/">TextDiff</a></li><li><a class="tocitem" href="../../../lib/internals/utilities/">Utilities</a></li><li><a class="tocitem" href="../../../lib/internals/writers/">Writers</a></li></ul></li></ul></li><li><a class="tocitem" href="../../../release-notes/">Release notes</a></li></ul><div class="docs-version-selector field has-addons"><div class="control"><span class="docs-label button is-static is-size-7">Version</span></div><div class="docs-selector control is-expanded"><div class="select is-fullwidth is-size-7"><select id="documenter-version-selector"></select></div></div></div></nav><div class="docs-main"><header class="docs-navbar"><a class="docs-sidebar-button docs-navbar-link fa-solid fa-bars is-hidden-desktop" id="documenter-sidebar-button" href="#"></a><nav class="breadcrumb"><ul class="is-hidden-mobile"><li><a class="is-disabled">Manual</a></li><li><a href="../">Hosting Documentation</a></li><li class="is-active"><a href>SSH Deploy Keys Walkthrough</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href>SSH Deploy Keys Walkthrough</a></li></ul></nav><div class="docs-right"><a class="docs-navbar-link" href="https://github.com/JuliaDocs/Documenter.jl" title="View the repository on GitHub"><span class="docs-icon fa-brands"></span><span class="docs-label is-hidden-touch">GitHub</span></a><a class="docs-navbar-link" href="https://github.com/JuliaDocs/Documenter.jl/blob/master/docs/src/man/hosting/walkthrough.md" title="Edit source on GitHub"><span class="docs-icon fa-solid"></span></a><a class="docs-settings-button docs-navbar-link fa-solid fa-gear" id="documenter-settings-button" href="#" title="Settings"></a><a class="docs-article-toggle-button fa-solid fa-chevron-up" id="documenter-article-toggle-button" href="javascript:;" title="Collapse all docstrings"></a></div></header><article class="content" id="documenter-page"><h1 id="SSH-Deploy-Keys-Walkthrough"><a class="docs-heading-anchor" href="#SSH-Deploy-Keys-Walkthrough">SSH Deploy Keys Walkthrough</a><a id="SSH-Deploy-Keys-Walkthrough-1"></a><a class="docs-heading-anchor-permalink" href="#SSH-Deploy-Keys-Walkthrough" title="Permalink"></a></h1><p>If the instructions in <a href="../#Authentication:-SSH-Deploy-Keys">Authentication: SSH Deploy Keys</a> did not work for you (for example, <code>ssh-keygen</code> is not installed), don't worry! This walkthrough will guide you through the process. There are three main steps:</p><ol><li><a href="#Generating-an-SSH-Key">Generating an SSH Key</a></li><li><a href="#Adding-the-Public-Key-to-GitHub-or-Gitea-such-as-Codeberg">Adding the Public Key to GitHub or Gitea such as Codeberg</a></li><li><a href="#Adding-the-Private-Key">Adding the Private Key</a></li></ol><h2 id="Generating-an-SSH-Key"><a class="docs-heading-anchor" href="#Generating-an-SSH-Key">Generating an SSH Key</a><a id="Generating-an-SSH-Key-1"></a><a class="docs-heading-anchor-permalink" href="#Generating-an-SSH-Key" title="Permalink"></a></h2><p>The first step is to generate an SSH key. An SSH key is made up of two components: a <em>public</em> key, which can be shared publicly, and a <em>private</em> key, which you should ensure is <strong>never</strong> shared publicly.</p><p>The public key usually looks something like this</p><pre><code class="nohighlight hljs">ssh-rsa [base64-encoded-key] [optional-comment]</code></pre><p>And the private key usually look something like this</p><pre><code class="nohighlight hljs">-----BEGIN RSA PRIVATE KEY-----
... base64-encoded key over several lines ...
-----END RSA PRIVATE KEY-----</code></pre><h3 id="If-you-have-ssh-keygen-installed"><a class="docs-heading-anchor" href="#If-you-have-ssh-keygen-installed">If you have <code>ssh-keygen</code> installed</a><a id="If-you-have-ssh-keygen-installed-1"></a><a class="docs-heading-anchor-permalink" href="#If-you-have-ssh-keygen-installed" title="Permalink"></a></h3><p>If you have <code>ssh-keygen</code> installed, but <code>DocumenterTools.genkeys()</code> didn't work, you can generate an SSH key as follows. First, generate a key using <code>ssh-keygen</code> and save it to the file <code>privatekey</code>:</p><pre><code class="language-julia hljs">shell> ssh-keygen -N "" -f privatekey</code></pre><p>Next, we need to encode the private key in Base64. Run the following command:</p><pre><code class="language-julia hljs">julia> using Base64
julia> read("privatekey", String) |> base64encode |> println</code></pre><p>Copy and paste the output somewhere. This is your <em>private key</em> and is required for the last step.</p><p>Now we need to get the public key. Run the following command:</p><pre><code class="language-julia hljs">julia> read("privatekey.pub", String) |> println</code></pre><p>Copy and paste the output somewhere. This is your <em>public key</em> and is required for the step <a href="#Adding-the-Public-Key-to-GitHub-or-Gitea-such-as-Codeberg">Adding the Public Key to GitHub or Gitea such as Codeberg</a>.</p><h3 id="If-you-do-not-have-ssh-keygen"><a class="docs-heading-anchor" href="#If-you-do-not-have-ssh-keygen">If you do not have <code>ssh-keygen</code></a><a id="If-you-do-not-have-ssh-keygen-1"></a><a class="docs-heading-anchor-permalink" href="#If-you-do-not-have-ssh-keygen" title="Permalink"></a></h3><p>If you're using Windows, you probably don't have <code>ssh-keygen</code> installed. Instead, we're going to use a program called PuTTY. The first step in the process to generate a new SSH key is to download PuTTY:</p><ul><li>Download and install <a href="https://www.chiark.greenend.org.uk/~sgtatham/putty/">PuTTY</a></li></ul><p>PuTTY is actually a collection of a few different programs. We need to use PuTTYgen. Open it, and you should get a window that looks like:</p><p><img src="../puttygen.png" alt/></p><p>Now we need to generate a key.</p><ul><li>Click the "Generate" button, then follow the instructions and move the mouse around to create randomness.</li></ul><p>Once you've moved the mouse enough, the window should look like:</p><p><img src="../puttygen-generated.png" alt/></p><p>Now we need to save the public key somewhere.</p><ul><li>Copy the text in the box titled "Public key for pasting into OpenSSH authorized_keys file" and paste it somewhere for later. This is your <em>public key</em> and is required for the step <a href="#Adding-the-Public-Key-to-GitHub-or-Gitea-such-as-Codeberg">Adding the Public Key to GitHub or Gitea such as Codeberg</a></li></ul><p>Finally, we need to save the private key somewhere.</p><ul><li><p>Click the "Conversions" tab, and then click "Export OpenSSH key". Save that file somewhere. That file is your <em>private key</em> and is required for the last step.</p><p><img src="../puttygen-export-private-key.png" alt/></p><div class="admonition is-info"><header class="admonition-header">Note</header><div class="admonition-body"><p>Don't save your key via the "Save private key" button as this will save the key in the wrong format.</p></div></div></li></ul><p>If you made it this far, congratulations! You now have the private and public keys needed to set up automatic deployment of your documentation. The next steps are to add the keys to GitHub and Travis.</p><h2 id="Adding-the-Public-Key-to-GitHub-or-Gitea-such-as-Codeberg"><a class="docs-heading-anchor" href="#Adding-the-Public-Key-to-GitHub-or-Gitea-such-as-Codeberg">Adding the Public Key to GitHub or Gitea such as Codeberg</a><a id="Adding-the-Public-Key-to-GitHub-or-Gitea-such-as-Codeberg-1"></a><a class="docs-heading-anchor-permalink" href="#Adding-the-Public-Key-to-GitHub-or-Gitea-such-as-Codeberg" title="Permalink"></a></h2><p>In this section, we explain how to upload a public SSH key to GitHub and Gitea such as Codeberg. By this point , you should have generated a public key and saved it to a file. If you haven't done this, go read <a href="#Generating-an-SSH-Key">Generating an SSH Key</a>.</p><p>Go to <code>https://github.com/[YOUR_USER_NAME]/[YOUR_REPO_NAME]/settings/keys</code> for GitHub and <code>https://somegiteaname.org/[YOUR_USER_NAME]/[YOUR_REPO_NAME]/settings/keys</code> and click "Add deploy key". You should get to a page that looks like,:</p><p><strong>GitHub</strong></p><p><img src="../github-add-deploy-key.png" alt="github-add-deploy-key"/></p><p><strong>Gitea</strong></p><p><img src="../gitea-codeberg-add-deploy-key.png" alt="gitea-codeberg-add-deploy-key"/></p><p>Now we need to fill in three pieces of information.</p><ol><li>Have "Title" be e.g. "Documenter".</li><li>Copy and paste the <em>public key</em> that we generated in the <a href="#Generating-an-SSH-Key">Generating an SSH Key</a> step into the "Key" or "Content" field.</li><li>Make sure that the "Allow write access" box is checked.</li></ol><p>Once you're done, click "Add key". Congratulations! You've added the public key to GitHub or your Gitea instance. The next step is to add the private key to Travis, GitHub, or Woodpecker Secrets.</p><h2 id="Adding-the-Private-Key"><a class="docs-heading-anchor" href="#Adding-the-Private-Key">Adding the Private Key</a><a id="Adding-the-Private-Key-1"></a><a class="docs-heading-anchor-permalink" href="#Adding-the-Private-Key" title="Permalink"></a></h2><p>In this section, we explain how to upload a private SSH key to Travis. By this point, you should have generated a private key and saved it to a file. If you haven't done this, go read <a href="#Generating-an-SSH-Key">Generating an SSH Key</a>.</p><p>First, we need to Base64 encode the private key. Open Julia, and run the command</p><pre><code class="language-julia hljs">julia> using Base64
julia> read("path/to/private/key", String) |> base64encode |> println</code></pre><p>If you are in a unix and unix-like system, you can just use <code>openssl</code> command with <code>tr</code> (for truncate) to generate your base64-encoded-key.</p><pre><code class="language-bash hljs">$ openssl enc -base64 -in path/to/your/private/key -out path/to/your/base/64/encoded/key
$ # We need to truncate the newlines
$ cat path/to/your/base/64/encoded/key | tr -d "\n"</code></pre><p>Copy the resulting output.</p><p>Go to <code>https://travis-ci.com/[YOUR_USER_NAME]/[YOUR_REPO_NAME]/settings</code>. Scroll down to the "Environment Variables" section. It should look like this:</p><p><img src="../travis-variables.png" alt/></p><p>Now, add a new environment variable called <code>DOCUMENTER_KEY</code>, and set its value to the output from the Julia command above (make sure to remove the surrounding quotes).</p><p>Finally, make sure that the "Display value in build log" is left switched off and then click "Add". Congratulations! You've added the private key to Travis.</p><div class="admonition is-warning"><header class="admonition-header">Security warning</header><div class="admonition-body"><p>To reiterate: make sure that the "Display value in build log" option is <strong>OFF</strong> for the variable, so that it does not get printed when the tests run. This base64-encoded string contains the <em>unencrypted</em> private key that gives full write access to your repository, so it must be kept safe. Also, make sure that you never expose this variable in your tests, nor merge any code that does. You can read more about Travis environment variables in <a href="https://docs.travis-ci.com/user/environment-variables/#Defining-Variables-in-Repository-Settings">Travis User Documentation</a>.</p></div></div><hr/><p><strong>Final Remarks</strong></p><p>You should now be able to continue on with the <a href="../#Hosting-Documentation">Hosting Documentation</a>.</p></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../">« Hosting Documentation</a><a class="docs-footer-nextpage" href="../../other-formats/">Other Output Formats »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="auto">Automatic (OS)</option><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 1.3.0 on <span class="colophon-date" title="Saturday 2 March 2024 11:11">Saturday 2 March 2024</span>. Using Julia version 1.10.2.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>