mirror of
https://github.com/privatevoid-net/nix-super.git
synced 2024-11-10 08:16:15 +02:00
118 lines
4.4 KiB
XML
118 lines
4.4 KiB
XML
<refentry xmlns="http://docbook.org/ns/docbook"
|
|
xmlns:xlink="http://www.w3.org/1999/xlink">
|
|
|
|
<refnamediv>
|
|
<refname>nix-push</refname>
|
|
<refpurpose>push store paths onto a network cache</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<cmdsynopsis>
|
|
<command>nix-push</command>
|
|
<group choice='req'>
|
|
<arg choice='req'>
|
|
<arg choice='plain'><replaceable>archivesPutURL</replaceable></arg>
|
|
<arg choice='plain'><replaceable>archivesGetURL</replaceable></arg>
|
|
<arg choice='plain'><replaceable>manifestPutURL</replaceable></arg>
|
|
</arg>
|
|
<arg choice='req'>
|
|
<arg choice='plain'><option>--copy</option></arg>
|
|
<arg choice='plain'><replaceable>archivesDir</replaceable></arg>
|
|
<arg choice='plain'><replaceable>manifestFile</replaceable></arg>
|
|
</arg>
|
|
</group>
|
|
<arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg>
|
|
</cmdsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
|
|
<refsection><title>Description</title>
|
|
|
|
<para>The command <command>nix-push</command> builds a set of store
|
|
paths (if necessary), and then packages and uploads all store paths in
|
|
the resulting closures to a server. A network cache thus populated
|
|
can subsequently be used to speed up software deployment on other
|
|
machines using the <command>nix-pull</command> command.</para>
|
|
|
|
<para><command>nix-push</command> performs the following actions.
|
|
|
|
<orderedlist>
|
|
|
|
<listitem><para>Each path in <replaceable>paths</replaceable> is
|
|
realised (using <link
|
|
linkend='rsec-nix-store-realise'><literal>nix-store
|
|
--realise</literal></link>).</para></listitem>
|
|
|
|
<listitem><para>All paths in the closure of the store expressions
|
|
stored in <replaceable>paths</replaceable> are determined (using
|
|
<literal>nix-store --query --requisites
|
|
--include-outputs</literal>). It should be noted that since the
|
|
<option>--include-outputs</option> flag is used, you get a combined
|
|
source/binary distribution.</para></listitem>
|
|
|
|
<listitem><para>All store paths determined in the previous step are
|
|
packaged and compressed into a <command>bzip</command>ped NAR
|
|
archive (extension <filename>.nar.bz2</filename>).</para></listitem>
|
|
|
|
<listitem><para>A <emphasis>manifest</emphasis> is created that
|
|
contains information on the store paths, their eventual URLs in the
|
|
cache, and cryptographic hashes of the contents of the NAR
|
|
archives.</para></listitem>
|
|
|
|
<listitem><para>Each store path is uploaded to the remote directory
|
|
specified by <replaceable>archivesPutURL</replaceable>. HTTP PUT
|
|
requests are used to do this. However, before a file
|
|
<varname>x</varname> is uploaded to
|
|
<literal><replaceable>archivesPutURL</replaceable>/</literal><varname>x</varname>,
|
|
<command>nix-push</command> first determines whether this upload is
|
|
unnecessary by issuing a HTTP HEAD request on
|
|
<literal><replaceable>archivesGetURL</replaceable>/</literal><varname>x</varname>.
|
|
This allows a cache to be shared between many partially overlapping
|
|
<command>nix-push</command> invocations. (We use two URLs because
|
|
the upload URL typically refers to a CGI script, while the download
|
|
URL just refers to a file system directory on the
|
|
server.)</para></listitem>
|
|
|
|
<listitem><para>The manifest is uploaded using an HTTP PUT request
|
|
to <replaceable>manifestPutURL</replaceable>. The corresponding
|
|
URL to download the manifest can then be used by
|
|
<command>nix-pull</command>.</para></listitem>
|
|
|
|
</orderedlist>
|
|
|
|
</para>
|
|
|
|
<para>TODO: <option>--copy</option></para>
|
|
|
|
</refsection>
|
|
|
|
|
|
<refsection><title>Examples</title>
|
|
|
|
<para>To upload files there typically is some CGI script on the server
|
|
side. This script should be be protected with a password. The
|
|
following example uploads the store paths resulting from building the
|
|
Nix expressions in <filename>foo.nix</filename>, passing appropriate
|
|
authentication information:
|
|
|
|
<screen>
|
|
$ nix-push \
|
|
http://foo@bar:server.domain/cgi-bin/upload.pl/cache \
|
|
http://server.domain/cache \
|
|
http://foo@bar:server.domain/cgi-bin/upload.pl/MANIFEST \
|
|
$(nix-instantiate foo.nix)</screen>
|
|
|
|
This will push both sources and binaries (and any build-time
|
|
dependencies used in the build, such as compilers).</para>
|
|
|
|
<para>If we just want to push binaries, not sources and build-time
|
|
dependencies, we can do:
|
|
|
|
<screen>
|
|
$ nix-push <replaceable>urls</replaceable> $(nix-instantiate $(nix-store -r foo.nix))</screen>
|
|
|
|
</para>
|
|
|
|
</refsection>
|
|
|
|
</refentry>
|