SAMIZDAT

The Samizdat.toml manifest

When you create a new SAMIZDAT project with samizdat init, you automatically get a file in your directory called Samizdat.toml. This file controls how the SAMIZDAT CLI will manage the series associated with your project. This article is an overview on the file and how you can use it in your workflow.

Profiles

SAMIZDAT works on two profiles (i.e., modes): build and release. This is directly reflected in the structure of Samizdat.toml: there is a series section for release settings and a debug section for debug settings. SAMIZDAT isolates both kinds of builds in different series, each with its own keypair. As the name implies, debug builds are meant for local development only and are not for public consumption.

What “not for public consumption” means here is a bit subtle. The [debug] profile publishes to a separate debug series with its own keypair. Editions on the debug series are NOT announced to the rest of the network, so no remote node will pick them up just because the hub broadcasts an announcement. However, the objects themselves DO exist on your local node and can be fetched by anyone who happens to know their content hashes. The isolation is “unannounced, separate identity”, not “encrypted at rest”.

On the other hand, release builds are the real-deal you expect: they are open to the world and new editions are announced (unless explicitly silenced with the --no-announce flag on commit).

Profile sections: series and debug

Both sections admit the same keys, which are:

  1. The nickname of the series owner (i.e., the public and private keypair). The nickname is node-local; the public identifier on the network is the series public key.
  2. The public-key corresponding to the target series.
  3. A ttl: a suggestion of how much time a node should wait to poll again the network for new editions. This field is optional and defaults to the value "1 hour".
    • In debug mode, you can set this value, but it has no effect.

The build section

The build section defines how a new edition should be built. For this, you need to specify two keys:

  1. A folder containing the final structure of the contents that will form this edition under the key base.
  2. An optional build script, which can be used to mount the output folder (e.g., running webpack or npm run something) under the key run. For the build script, the following environment variables are set:
    • SAMIZDAT_RELEASE: is set to something not empty if in release mode and to empty if in debug mode.

The .Samizdat.priv private manifest

Finally, together with the Samizdat.toml, a second file is generated when you call samizdat init: .Samizdat.priv. This file contains the private keys corresponding to both release and debug series. Since it contains only private information, it cannot be put in the main manifest and should be kept away from version control systems such as Git (we strongly recommend you to add it to your .gitignore). Be careful with whom you share this file! Every person with access to its contents can create new editions of your series, essentially taking control of it irreversibly.

We will not elaborate on the structure of the private manifest here, as there is no need to customize it. Since all it contains are the private keys, you may use it and pass it around as is.