What is Fission?

Fission powers next generation app publishing.

For developers, they can design a user app using only front end and design skills. The web native app can be installed by 10 or 10,000 users, just like mobile or desktop software. Because the app is running on the user's computer, you can focus on finding new users and adding new features, rather than having to learn DevOps or server scaling.

People using apps create a secure identity in their browsers. Every Fission account is linked to a file system, available in any browser. Much like an open source iCloud, users give permissions to apps, and can access their files from anywhere. Users can browse their file system, both public and private, and mix and match which apps they use, just like they're used to with mobile and desktop apps.

Developers

Get started by installing the Fission CLI »

Users

Learn more about Fission Accounts, and try one out by installing the Drive app »

Fission Dashboard shows the verification status of your account. You can resend your verification email if it ended up in your spam.

Like all Fission apps -- including the ones made by Fission directly -- you need to give permission to the Dashboard app to access your account info.

Web Linking

To have access to your account across multiple devices, you need to link them.

When you visit an app on a new device and Sign in with Fission, or if you go directly to the Fission Auth page, you'll be prompted to either create a new account or link an existing one:

If you have an account already, click the sign in button:

The only thing you need to know is your username. Enter it, and hit the link account button:

As you can see, you are now being asked to open the Fission Auth page on your other device. This might be your other computer or perhaps your phone. There is also a short message telling us that this is for the boris0902 username.

Once you open the Fission Auth page on your other device, it will detect the linking request and display a page like this.

The new device you are linking should show the same numbers:

Since we can see the numbers are the same, we can go ahead and hit the "Approve" button, and you'll see this success message.

Switching to the new device you were linking, you'll see this message:

Now you can use either device with full authorization

And yes, this works on mobile too:

Command Line Linking

The Linking an existing user guide has details on linking accounts used at the command line.

When you create a Fission Account, whether signing up on the web or using the command line as a developer, it creates a username and email address in our service database, and also a private / public key pair representing that account.

We also create a Fission Web Native File System (WNFS) attached to your account, and given you access to Fission Drive, which lets you browse all your files, access them from any browser, and see which apps are attached to your file system.

We verify your email address, and can use that to help manage aspects of your service with us. You hold access to the keys connected to your account, and sign in happens automatically.

We encourage you to "link" your account to multiple devices -- your desktop and your phone, your home and your work computers, and so on. These devices can then be used to login, or link more accounts. You can read more about Account Linking »

Signing out of Fission Apps

There is no "sign out" for a Fission-powered app. You use your key to do a passwordless login, stored in your local desktop browser, mobile web browser, or your local desktop file system with the command line developer tool.

While your device is linked with a key, Fission apps will check that you have a key with the proper permission, and will just let you right in, without having to remember a password or even a username.

This is like your smartphone: only a single user is "logged in" to their personal phone, and they aren't shared.

We don't delete the data that the app stored for you, since it's stored in your own Fission File System -- just like data is stored on your phone.

App Permissions

As part of signing into an app, an app will ask for certain permissions. Right now, these are mostly related to access to your file system.

By default, every app needs access to an App Folder. You'll need to at least grant access to an App Folder for the app to function correctly.

Revoking App Access

Instead of signing out, you may want to revoke -- or delete -- an app's access to your account.

Shared Devices

Browsers and desktop computers aren't smartphones, and they do get shared. You can unlink a device -- remove your key -- by visiting the Fission Auth page.

Multiple Accounts per Device

You may create multiple Fission accounts, but you'll need a unique email address and username for each one. You'll also need to use Browser Profiles to be able to access them at the same time on the same machine, as the keys that grant access are stored in the browser.

Installing the Fission CLI

The Fission command line interface (CLI) is the most common way for developers to interact with Fission services.

macOS with Homebrew

Use the Homebrew recipe to install the CLI on macOS. This taps and installs in one command:

brew install fission-suite/fission/fission-cli

If you have any issues, check that libcrypto1.1 installed and linked on your system.

You can also follow the next section for a manual install on macOS.

Linux and Manual Installation

Head over to our releases page on Github and download the latest release for your operating system.

Grant execute permissions and move the binary onto to your PATH. For example, on Ubuntu 20.04:

chmod a+x ./fission-cli-ubuntu-20.04
sudo mv ./fission-cli-ubuntu-20.04 /usr/local/bin/fission

Check that the CLI was installed correctly.

$ fission --help
Fission makes developing, deploying, updating, and iterating on web apps quick
and easy.

Usage: fission (SHORTCUT | COMMAND | --version) [-v|--verbose]
  CLI to interact with Fission services

If you have any issues, check that you have libssl1.1 (installed with OpenSSL) and libtinfo5 (or libtinfo6). Most recent Linux distributions will already have these libraries installed.

Clock Configuration

Check that your clock is accurate. Account linking depends on an accurate clock and may fail due to clock drift.

Mismatched clocks between a host system and container or VM may also cause issues.

Upgrading the CLI

Run fission --version to check if you are using an old version of the CLI.

To upgrade the CLI on macOS, brew uninstall and brew untap to reset brew.

brew uninstall fission-cli
brew untap fission-suite/fission

Reinstall with brew tap and brew install.

brew tap fission-suite/fission
brew install fission-cli

On Linux, repeat the installation steps listed above, leaving out the installation of the additional libraries.

Fission users can recover a lost account with a Recovery Kit. You can create a Recovery Kit in the Fission Dashboard to ensure you will always have access to your account.

Make a Recovery Kit

Sign in to the Fission Dashboard and select Recovery Kit.

To create a Recovery Kit, you need to grant the Fission Dashboard access to your private files. This step is necessary for the Dashboard to recover your private files.

Allow creating a recovery kit and grant permission in the Fission Auth Lobby.

After granting permission, you can create a Recovery Kit.

The recovery kit should be stored somewhere safe. Anyone with access to your Recovery Kit can access your private files. If you lose your Recovery Kit, you will not be able to recover your account.

Download your Recovery Kit and save it somewhere safe.

We recommend you store it on a device or storage medium that you will not easily lose.

Recover your Account

If you have lost access to your account, you can recover it with a Recovery Kit from the Fission Dashboard.

Select the Recover your account option below the sign in button.

You will need your Recovery Kit and access to the email you used to create the account.

Drag your recovery kit onto the upload box or click the box to select it from your file system. Fission Dashboard will import your recovery kit.

After Fission Dashboard imports your Recovery Kit, select send email.

Fission will send you verification email. Click on the link in the email and the recovery page will give you an option to recover your account.

Select recover account and re-link your account by signing into the Fission Auth Lobby.

Make sure to keep the recovery page open while you re-link your account.

The Fission Auth Lobby and account recovery page will show you confirmation codes.

When you are satisfied that the codes match, confirm in the account recovery page.

After confirming, Fission will recover your account, and you can access your files again.

Your Recovery Kit will work again if you need to recover your account in the future.

Fission will occasionally change how your file system is stored to enable new features, improve performance, and improve security. Some of these changes require a file system migration.

Because Fission has no control over your file system, we cannot migrate your file system for you. To help you with migrations, we've developed a command-line tool that upgrades your file system to the latest version.

When to migrate your file system

If your file system is outdated, you will see a message like this in the Auth Lobby (https://auth.fission.codes):

If you decide that your username and data are not worth keeping, go to https://auth.fission.codes and click the text "remove this device" on the bottom of the page. Keep in mind that you will not be able to access data associated with the account afterward.

After removing a device, you will be able to create a new account. New accounts are always created at the latest file system version.

Running a migration

At the moment, running a migration requires familiarity working with the command line on your machine.

Step 1: Install the Fission CLI

Step 2: Link your web account to your command line

The Webnative File System (WNFS) migration tool will use your linked credentials when migrating your file system.

Step 3: Install NPM following the instructions for your operating system

Step 4: Install wnfs-migration

You can now install the migration CLI tool with npm:

npm install --global wnfs-migration

Step 5: Run wnfs-migration

$ wnfs-migration
Looking up data root for [...]
Data root is bafybei[...]
Loading IPFS...
Connected to local ipfs node, version 0.9.0
Connected to the Fission IPFS Cluster
Looking up your filesystem version (https://[...].files.fission.name/version)
Your filesystem currently is at version 1.0.0
Processing public/.well-known
Processing public/.well-known/exchange
[...]
Processing private/Documents
Finished migration: bafybei[...]
? Are you sure you want to overwrite your filesystem with a migrated version? (Y/n)

At this point, wnfs-migration has migrated a local copy of your WNFS. It will then ask you to confirm that you want to overwrite the synced version of your file system on the Fission servers.

Enter Y to confirm or n to decline and abort the migration process. If you confirm, wnfs-migration will sync your migrated file system:

Created authorization UCAN. Updating data root... # this will take some time
Migration done!
Shutting down IPFS...

All of the apps that you have published with your account are listed on the Apps page.

Create a new app from the Dashboard

Manage apps you've created

Fission Drive is currently a preview release of our upcoming file storage and identity system that lets you take your files anywhere, encrypted end-to-end as well as for public hosting of files, websites, and apps.

The Preview release is an exploration of the interface, and currently supports only public files.

Enter any IPFS Hash

You can browse any IPFS directory, not just those hosted on Fission, by entering in the hash, or Content ID (CID), of a directory.

Features

Dark & Light Mode

Preview supports system wide / browser settings for dark vs. light mode and will switch automatically when you change those settings.

File Previews

Clicking on an image will give you a file preview.

Click on the double arrows in the top right hand corner to embiggen the preview to full screen. Hit the X to close the preview.

The "Open in new tab" link will give you a permanent link for sharing the current file, using the Fission IPFS gateway.

Mobile Support

Yes, this works on mobile!

Keyboard Shortcuts

Use arrow keys to navigate, enter to open preview.

The Fission CLI and Webnative SDK are developer tools for interacting with Fission services. This section will introduce the technologies used in these tools and describe how they work on your machine and in the broader network.

Network

The Fission CLI and Webnative SDK use the InterPlanetary File System (IPFS) for networking and data transfer. IPFS uses peer-to-peer communication to exchange data between peers.

In the browser, the Webnative SDK connects with Fission peers to access and update user data. Likewise, the Fission CLI connects with Fission peers to publish websites. In both cases, you can substitute your own peers by running your own Fission server.

The Fission CLI is a developer tool for working with apps and managing your account on the Fission platform.

Structure

The Fission CLI uses multipart commands with the structure:

Commands group related subcommands into operations on apps or accounts. Options extend functionality or display help information.

Shortcuts combine a command and subcommand into a shortcut command:

The options that would apply to the multipart command also apply to the shortcut.

Help

The --help option displays a quick reference at any command level.

At the top level, fission --help displays a high-level summary of all commands and shortcuts.

Setup

With fission installed, we are ready to set it up on your local machine. If this is your first time using fission, you will be prompted for a username and an email to confirm your new account.

A private key has been generated for your machine and saved in the ~/.config/fission/key/ directory. This key secures your communication with Fission services and works like using an SSH key to connect to GitHub.

Account Linking

Create a simple webpage

Let's publish a simple webpage with Fission! We will write a simple webpage, register it as a Fission app, and publish it to the web.

Create a project directory and an index.html file.

Add some content to index.html:

Run fission app register command to initialize the webpage as a Fission app. You will be prompted for a build directory.

Press enter to set hello-universe as your build directory, and fission will initialize your app.

Fission will create a fission.yaml file with your app configuration.

Run fission app publish to publish the webpage.

Copy the URL from the last line and paste it into your web browser to view the webpage live on the web. Nice and simple!

Use fission setup, fission user whoami, and fission login to set up your account, display your username, and link your account in web browser.

Setup a new user

The fission setup command registers your account with Fission or links to your existing Fission account.

When you register a new account, you will be prompted for a username and an email. Fission will send you an email to confirm your account and complete your registration.

The fission setup command will create a global config.yaml file in your ~/.config/fission directory. See the guide for more information about the config.yaml file.

Display user information

Use fission user whoami to display your username.

Linking a web browser

You can link your Fission account in a web browser to interact with Fission-enabled apps. The fission login command sets up the CLI to listen for requests to link your account.

The browser window and command line will display confirmation codes. Verify that the confirmation codes match and grant access at the command line.

The browser window will update to show that you have successfully linked your account.

Linking from a web account

If you are signed into a Fission account in a web browser, you can link your account and use it at the command line.

Use fission setup to create and link a CLI user at your command line.

When prompted, enter Y to confirm you have an account and enter your username from the browser window. The auth lobby and CLI will display a confirmation code.

When you have confirmed that the codes match, approve in the browser, and the CLI will complete the setup process and link your account.

Setup with an existing key

You can set up your machine with an existing account if you have the machine_id.ed25519 key. Use --with-key argument and the path to your key.

Use fission generate credentials to generate key pairs and DIDs.

Generate Credentials

The fission generate credentials command generates a new Ed25519 key pair and an associated DID.

$ fission generate credentials
✅ Generated an Ed25519 key pair and associated DID
🗝️  Private key: <private-key>
🔑 Public key: <public-key>
🆔 DID: <DID>

See the W3C did:key Method specification for details on the derivation of DIDs from public keys.

You can add Webnative to a project by loading it from a CDN or installing it with a package manager.

CDN

For prototyping or experimentation, you can use the latest version of Webnative.

<script src="https://unpkg.com/webnative@latest/dist/index.esm.min.js"></script>

We recommend linking to a specific version in production to avoid unexpected changes.

Use the build from the global context.

const wn = self.webnative

Package Manager

We recommend installing Webnative with a package manager for larger projects that use build tools or bundlers.

Install Webnative with npm or your preferred package manager.

npm install webnative

Import Webnative in your application.

import * as wn from 'webnative'

The Webnative SDK empowers developers to build fully distributed web applications without needing a complex back-end. Webnative provides:

• User accounts using the browser's Web Crypto API or a blockchain wallet using the Webnative WalletAuth plugin

• Authorization using UCAN

• Encrypted file storage using the Webnative File System backed by IPLD

• Key management using the AWAKE protocol to link devices

• Platform APIs for publishing apps from the browser

Webnative applications work offline and store data encrypted for the user by leveraging the power of the web platform.

This guide walks through the fundamental concepts for working with the Webnative. We also publish an API reference at webnative.fission.app and you can view the source code on GitHub.

You can also view the API reference at deno.land and paka.dev.

You can use the Webnative SDK by creating a Webnative program. Here is a minimal example:

const program = await wn.program({
  // `namespace` can also be just a string; it's used as an identifier for caches.
  // If you're developing multiple apps on the same localhost port,
  // make sure these differ.
  namespace: { creator: "Nullsoft", name: "Winamp" }

}).catch(error => {
  switch (error) {
    case webnative.ProgramError.InsecureContext:
      // Webnative requires HTTPS
      break;
    case webnative.ProgramError.UnsupportedBrowser:
      // Browsers must support IndexedDB
      break;
  }

})

Program

A Webnative program is a set of components and utilities for building a distributed web application.

export type Program = ShortHands & {
  auth: AuthenticationStrategy
  capabilities: {
    collect: () => Promise<Maybe<string>> // returns username
    request: (options?: CapabilitiesImpl.RequestOptions) => Promise<void>
    session: (username: string) => Promise<Maybe<Session>>
  }
  configuration: Configuration
  components: Components
  session: Maybe<Session>
}

We'll cover each part of a program in upcoming sections. As a quick summary:

• Session. A session including a username and a filesystem instance. A session will be created from an authentication strategy or requested capabilities depending on which approach your application takes.

• Authentication Strategy. A set of functions for registering users and linking devices.

• Capabilities. A set of functions for requesting authorization from another app.

• Configuration. The configuration used to instantiate the program.

• Components. Component implementations for authentication strategy, capabilities, crypto, storage, depot, manners, and references.

• Shorthands. Helper functions provided for easy access.

Configuration

You can configure a program with a namespace parameter and a few optional parameters:

export type Configuration = {
  namespace: string | AppInfo
  debug?: boolean
  fileSystem?: {
    loadImmediately?: boolean
    version?: string
  }
  permissions?: Permissions
  userMessages?: UserMessages
}

Namespace

We saw a namespace earlier in our minimal example:

namespace: { creator: "Nullsoft", name: "Winamp" }

A namespace isolates an application in browser storage. This isolation means you can work on multiple apps on localhost at the same port and not worry about them interacting or conflicting. Provide each app a namespace, and they will exist independently.

You can also set the namespace as a string:

namespace: "nullsoft-winamp"

Debug

The debug flag determines whether Webnative should log detailed debugging information to the console. The default value is false.

Filesystem options

The loadImmediately flag determines if Webnative should load the filesystem at initialization. The default value is true.

The filesystem can be loaded after initialization using the program.loadFileSystem shorthand function. In most cases, you will want to load the filesystem immediately, but deferring can sometimes be useful. For example, you can load the filesystem in a Worker after initialization.

The version sets the filesystem version. The version defaults to the latest stable version of WNFS.

Permissions

Permissions are the capabilities to be requested from another application. We'll cover permissions in more detail in the Requesting Capabilities section.

User messages

User messages are alerts that report to the user when the current version of Webnative does not support their filesystem. You can update these messages to provide users with your support information.

Custom Components

You can deeply customize a Webnative program by providing component implementations. We'll discuss custom components in the Components section.

Fission stores global and app configuration options in YAML files. The global configuration is stored in a config.yaml file and app configurations are stored in fission.yaml files.

Global Fission YAML

After you run fission user setup, you will have a global config.yaml in your ~/.config/fission/ folder. You can open config.yaml in a text editor or display it at the command line.

more ~/.config/fission/config.yaml

The default global config.yaml will looks something like this:

ignore: []
username: fission
root_proof: null
server_did: did:key:zStEZpzSMtTt9k2vszgvCwF4fLQQSyA15W5AQ4z3AR6Bx4eFJ5crJFbuGxKmbma4
peers:
- /dns4/node.runfission.com/tcp/4001/ipfs/QmVLEz2SxoNiFnuyLpbXsH6SvjPTrHNMU88vCQZyhgBzgw
- /dns4/node.fission.systems/tcp/4003/wss/p2p/QmVLEz2SxoNiFnuyLpbXsH6SvjPTrHNMU88vCQZyhgBzgw
- /dns4/production-ipfs-cluster-us-east-1-node0.runfission.com/tcp/4001/p2p/12D3KooWFSAbpiAeKHnVyqMqrdvAtu8C3veePHi36bZGNM2qv42q
- /dns4/production-ipfs-cluster-us-east-1-node0.runfission.com/tcp/4003/wss/p2p/12D3KooWFSAbpiAeKHnVyqMqrdvAtu8C3veePHi36bZGNM2qv42q
- /dns4/production-ipfs-cluster-us-east-1-node1.runfission.com/tcp/4001/p2p/12D3KooWNntMEXRUa2dNgkQsVgzao6zGSYxm1oAs83YtRy6uBuxv
- /dns4/production-ipfs-cluster-us-east-1-node1.runfission.com/tcp/4003/wss/p2p/12D3KooWNntMEXRUa2dNgkQsVgzao6zGSYxm1oAs83YtRy6uBuxv
- /dns4/production-ipfs-cluster-us-east-1-node2.runfission.com/tcp/4001/p2p/12D3KooWQ2hL9NschcJ1Suqa1TybJc2ZaacqoQMBT3ziFC7Ye2BZ
- /dns4/production-ipfs-cluster-us-east-1-node2.runfission.com/tcp/4003/wss/p2p/12D3KooWQ2hL9NschcJ1Suqa1TybJc2ZaacqoQMBT3ziFC7Ye2BZ
- /dns4/production-ipfs-cluster-eu-north-1-node0.runfission.com/tcp/4001/p2p/12D3KooWDTUTdVJfW7Rwb6kKhceEwevTatPXnavPwkfZp2A6r1Fn
- /dns4/production-ipfs-cluster-eu-north-1-node0.runfission.com/tcp/4003/wss/p2p/12D3KooWDTUTdVJfW7Rwb6kKhceEwevTatPXnavPwkfZp2A6r1Fn
- /dns4/production-ipfs-cluster-eu-north-1-node1.runfission.com/tcp/4001/p2p/12D3KooWRwbRrSN2cPAKz4yt1vxBFdh53CpgWjSFK5hZPkzHHz5h
- /dns4/production-ipfs-cluster-eu-north-1-node1.runfission.com/tcp/4003/wss/p2p/12D3KooWRwbRrSN2cPAKz4yt1vxBFdh53CpgWjSFK5hZPkzHHz5h
update_checked: 2021-06-08T22:47:53.507087194Z
signing_key_path: /home/fission/.config/fission/key/machine_id.ed25519

ignore

Ignore is a list of files you don't want fission app publish to publish. For example, you might add commonly ignored files and secrets.

ignore: [".DS_Store", ".env"]

Ignore follows the same conventions used in a .gitignore file.

username

Username is a name you select for yourself during fission setup.

root_proof

The UCAN that was used to link from another device or browser. null if the account was created on this device.

server_did

Server DID is the identity of the Fission server that authenticates your requests when using the Fission CLI.

peers

We configure your machine to directly connect to our servers. The peers are the IP addresses and fingerprints of our servers.

You can also fetch our active public peers from the peers endpoint: https://runfission.com/ipfs/peers

update_checked

Timestamp of the last check for an updated version of the CLI.

signing_key_path

The path to the key used to sign requests made when using the Fission CLI.

Fission YAML for Apps

When you create a new app with fission app register, a fission.yaml file is created in the directory where you ran the command. The default fission.yaml file looks something like:

ignore: []
url: junior-angular-tulip.fission.app
build: ./dist

ignore

Ignore works the same as the ignore in the global configuration. You can use it to list files that you do not want to publish.

ignore:
 - node_modules
 - *.psd

You might use it to ignore a directory like node_modules or all files with an extension like Photoshop .psd files.

url

The URL where your app is viewable after it has been published.

build

The build directory is the directory the Fission CLI will publish. Use this when you have a build step that produces a production-ready version of your application.

The build directory is set as a relative path from the location of the fission.yaml file.

Use the fission app command and its subcommands to work with apps. The main operations are registering an app, publishing an app, and displaying information about an app.

Register an app

The fission app register command initializes a new app and links it to your Fission account.

$ fission app register
👷 Build directory (.): 
✅ App initialized as big-narrow-fuchsia-elf.fission.app
⏯️  Next run fission app publish or fission app publish --watch to sync data
💁 It may take DNS time to propagate this initial setup globally. In this case, 
you can always view your app at 
https://ipfs.runfission.com/ipns/big-narrow-fuchsia-elf.fission.app

You will be prompted for a build directory. The Fission CLI will publish your app from the build directory you select.

If you are using a common build directory, the Fission CLI will detect it when you run fission app register and suggest it. You accept the suggestion or enter another build directory as a relative path from the fission.yaml file.

The Fission CLI will create a fission.yaml configuration file with a list of files to ignore, a URL where your app will be viewable after it is published, and a build directory. See the Fission YAML guide for more information about the fission.yaml file.

The fission app register command has advanced options:

$ fission app register --help
Usage: fission app register [--ipfs-bin BIN_PATH] [--ipfs-timeout SECONDS] 
                            [-v|--verbose] [-a|--app-dir PATH] 
                            [-b|--build-dir PATH] [-n|--name NAME]
  Initialize an existing app

Available options:
  --ipfs-bin BIN_PATH      Path to IPFS binary (default: `which ipfs`)
  --ipfs-timeout SECONDS   IPFS timeout (default: 300)
  -v,--verbose             Detailed output
  -a,--app-dir PATH        The file path to initialize the app in (app config,
                           etc) (default: ".")
  -b,--build-dir PATH      The file path of the assets or directory to sync
  -n,--name NAME           Optional app name
  -h,--help                Show this help text

Publish an app

Use the fission app publish command to publish your app to the web. Run this command from the directory that contains your app's fission.yaml configuration file.

The fission app publish command publishes your app and associates it with the URL in the fission.yaml file. After your app is published, the Fission CLI will output a success message and the URL for your app.

$ fission app publish
🕚🛫 App publish local preflight
✈️  Pushing to remote
🚀 Now live on the network
📝 DNS updated! Check out your site at:
🔗 big-narrow-fuchsia-elf.fission.app

The fission app publish command has advanced options:

$ fission app publish --help
Usage: fission app publish [--ipfs-bin BIN_PATH] [--ipfs-timeout SECONDS] 
                           [-v|--verbose] [--update-data ARG] [--update-dns ARG]
                           [-w|--watch] [PATH]
  Upload the working directory

Available options:
  --ipfs-bin BIN_PATH      Path to IPFS binary (default: `which ipfs`)
  --ipfs-timeout SECONDS   IPFS timeout (default: 300)
  -v,--verbose             Detailed output
  --update-data ARG        Upload the data (default: True)
  --update-dns ARG         Update DNS (default: True)
  -w,--watch               Watch for changes & automatically trigger upload
  PATH                     The file path of the assets or directory to
                           sync (default: "./")
  -h,--help                Show this help text

Continuously Update an App with Watch

You can continuously publish your app by adding the --watch option. The Fission CLI will watch your build directory and publish whenever it detects a change.

$ fission app publish --watch
🕚🛫 App publish local preflight
✈️  Pushing to remote
🚀 Now live on the network
📝 DNS updated! Check out your site at: 
🔗 big-narrow-fuchsia-elf.fission.app

This means that as you work in your local development environment, changes are continuously streamed online as you save. Note that some development environments have different code and output options than "production", but this will allow you to quickly and easily share a live online version with other people.

Display information about an app

Use fission app info to display the URL where your app is viewable.

$ fission app info
✅ App available at big-narrow-fuchsia-elf.fission.app

Delegation

The fission app delegate command delegates the capability to work with apps to a DID:

$ fission app delegate --app-name ancient-round-crab --did did:key:z6Mkfr7dWuKb2muJRLiqd7mNZ61iBQD9btiPHemdcHaXcF47
✅ Delegated a UCAN for ancient-round-crab to did:key:z6Mkfr7dWuKb2muJRLiqd7mNZ61iBQD9btiPHemdcHaXcF47
🎫 UCAN: eyJ1YXYiOiIxLjAuMCIsImFsZyI6IkVkRFNBIiwiY3R5IjpudWxsLCJ0eXAiOiJKV1QifQ.eyJuYmYiOjE2NTczMDM4NzMsImlzcyI6ImRp
ZDprZXk6ejZNa2tYYkxrYjFqaGNhdkNBeW1aa3pKcnY4eWNZVHRzVmU4QndycTlaZFpHbjRLIiwicHJmIjpudWxsLCJhdWQiOiJkaWQ6a2V5Ono2TWtm
cjdkV3VLYjJtdUpSTGlxZDdtTlo2MWlCUUQ5YnRpUEhlbWRjSGFYY0Y0NyIsImZjdCI6W10sInB0YyI6IkFQUEVORCIsInJzYyI6eyJhcHAiOiJhbmNp
ZW50LXJvdW5kLWNyYWIucnVuZmlzc2lvbi5jb20ifSwiZXhwIjoxNjU3MzA0MjAzfQ.lgMvPwJS3aGmLZp5j-dftuUaVktx6EOc4RkL5rATXjrDdqgs-
4CrIxmdq_JzWF1oEkiYYSjspfL9RQl95emFAQ

You can delegate apps you have registered on your machine or delegate from environment variables by setting FISSION_MACHINE_KEY and FISSION_APP_UCAN to an Ed25519 private key and a UCAN whose audience is associated with the key. Both environment variables must be set.

The command assumes least privilege by defaulting to Append potency and limiting the UCAN lifetime to five minutes. Both potency and lifetime can be set when more potency or a longer lifetime are desired.

The fission app delegate command has advanced options:

fission app delegate --help
Usage: fission app delegate (-a|--app-name NAME) (-d|--did DID) 
                            [-p|--potency POTENCY] [-l|--lifetime LIFETIME] 
                            [-q|--quiet]
  Delegate capability to an audience DID

Available options:
  -a,--app-name NAME       The target app
  -d,--did DID             An audience DID
  -p,--potency POTENCY     The potency to delegate. Options include Append,
                           Destroy, or Super_User. (default: "Append")
  -l,--lifetime LIFETIME   Lifetime in seconds before UCAN expires
                           (default: 300)
  -q,--quiet               Only output the UCAN on success
  -h,--help                Show this help text

Capabilities

Capabilities is an API that allows apps to request authorization from another app.

Capabilities includes:

• collect. Collects UCANs and file system secrets.

• request. Requests authorization from another app.

• session. Creates a session after authorization has been granted.

We saw earlier in Authentication Strategies how an app can register a user and link their account across devices. Authentication strategies are designed for use within a single web app across multiple devices.

Capabilities are an API for linking between apps. One app requests permission to access some set of resources from a second app with capability equal to or greater than the requested permissions. On user approval, the second app returns capability to the first app in the form of UCANs and file system secrets.

Requesting capabilities

Here is an example of requesting capabilities from the Fission Auth Lobby:

When Webnative redirects users to the Fission Auth Lobby, they will see a prompt with the permissions that your app has requested. The user can choose to accept or decline the request.

Either way, the Fission Auth Lobby redirects the user to your app. If the user accepted, Webnative will automatically create a session at program initialization.

Session

A session is an authenticated interaction between a user and a Webnative program. Sessions are typically long-lived and are based on a user controlling a key pair.

Webnative authenticates and authorizes a user who controls a key pair through:

• WebCrypto. The browser which supports non-exportable private keys.

• WalletAuth. A browser extension that supports blockchain wallets through the plugin.

• Requesting capabilities. Uses a WebCrypto key pair, but authorization must be requested from another app with equal or greater authority.

Creating a session

A session can be created through an or by . We'll look at each of these approaches in upcoming sections, but for now here is the Session class they create:

A session includes a session type, username, and an optional filesystem.

Session Type

The session type indicates how the session was created. The possible types include webCrypto and capabilities.

WalletAuth uses a blockchain wallet but delegates to a WebCrypto key pair. As a result, the session type when using WalletAuth is webCrypto.

Username

A username selected by the user at registration. When requesting capabilities, the user will already have a username from the app where they originally registered.

The username is a wallet address when using WalletAuth.

Filesystem

The Webnative SDK is built on a few foundational blocks, the Webnative File System (), , s, and s. How these pieces are bound to an identity, communicated to other devices and users, encrypted, and transferred, is customizable through components. By default, Webnative uses the Fission infrastructure, but you don't have to.

There are seven components:

• Auth. Responsible for , , and .

• Capabilities. Determines how are requested and collected.

• Crypto. How should private-public key pairs and symmetric keys be stored? How do I sign a message? Which key types should I support for the did:key method? What are my agent and sharing key pairs?

• Depot. Gets IPLD data in and out of your program by creating and referencing CIDs. File system data is brought in and shipped out through this component.

• Manners. Various behavioral elements. If the debug configuration flag is enabled, how does the logging happen, file system hooks, etc.

• Reference. Responsible for the sources of truth: the data root (root CID of WNFS), the DID root (your account DID, aka. root agent DID), DNS, and repositories of various items.

• Storage. Stores and retrieves ephemeral and session data.

Customization Examples

Walletauth

• The crypto component configures Webnative to work with the key pair used by an Ethereum wallet.

• The manners component alters how Webnative transfers the root file system encryption key. Using file system hooks, the key is encrypted and put on the public side of the file system. The wallet can always decrypt this key, enabling file system access no matter what device connects.

Manners

In this example, we'll add a file system hook and emojis to the debug messages.

Using Components

To use a different component than Webnative's defaults, all you have to do is pass them into the program. Alternatively, if you have a whole composition (see the section below), you can skip a step and directly use the assemble function. That's what the program function uses underneath.

Compositions

A composition is a full set of components.

Authentication strategies

An authentication strategy is a set of functions for registering and linking a user's account across devices.

A Webnative program includes an authentication strategy. Webnative provides a WebCrypto authentication strategy by default, but you can configure the strategy using the Components API.

An authentication strategy includes:

• accountConsumer. An event emitter that requests device linking from an authed device.

• accountProducer. An event emitter that provides device linking to an accountConsumer.

• isUsernameAvailable. Checks if a username is available.

• isUsernameValid. Checks if a username is valid.

• register. Registers a user with a username and an optional email.

• session. Creates a . Called after registration or device linking.

Registering a user

Here is how you register a user:

Our example checks if a username is valid and available, registers a user, and creates a session.

Agent DIDs

Each user device has an agent DID associated with the key pair on device. You can query the program to inspect the agent DID:

We call the DID registered with the server the root agent DID. Each time a device makes a request to the Fission server on behalf of a user, it must be the user's initial root device or a device with delegated authority from the root device.

Device linking

Device linking provides a secure mechanism for linking a user's account across devices or browsers.

Device linking occurs between an account producer (an authed device) and an account consumer (a device that would like to be linked). The devices bootstrap a secure channel to communicate, and the producer issues an account UCAN to the consumer that authorizes it to act on the user's behalf with full capability for 1000 years. So effectively, the newly linked device will have full access to the user's account for as long as it matters.

We want to note that no private keys are ever sent over the wire during device linking. Instead, each device is an agent with its own key pair and associated agent DID. The producer issues an account UCAN that delegates authority to the consumer's agent DID. When the consumer later makes a request to the Fission server, it provides the account UCAN as proof that it can act on the user's behalf.

When a user links a device, they should open a linking page on the authed device and the device they would like to link. The device to be linked needs to be configured with their username. We recommend the authed device display a QRCode or copy link that encodes the username as a query string param. The user can also manually enter their username on the device to be linked.

Here is an example of an account producer:

An account producer emits challenge and link events. The challenge is a PIN sent by the consumer.

Here is a matching account consumer:

An account consumer also emits challenge and link events. The consumer should create a session when the link event reports approval.

You can share a private file or directory with another Fission user:

Exchange keys

Private shared data uses public keys, which we call exchange keys, that live in a user's public filesystem under .well-known/exchange/. Exchange keys are unique per domain because webnative generates a key-pair per domain, so we need to add an exchange key to each domain that will accept shares. We can add an exchange key to a filesystem using:

The auth lobby automatically does this when we create our account, link a device, or authorise an application.

Creating a share

When the receiver of the share has their exchange key(s) set up, we're ready to create a share:

That will do an fs.publish() and consequently a data root update, so you'll want to wait until those are complete before accepting a share.

Resolving the share

The shareDetails contain a shareId used to accept or load a share.

By accepting a share, you create a symbolic link (aka. soft link) to the shared data in the /private/Shared with me/SENDER_USERNAME/ directory. In other words, accepting a share is fs.loadShare() plus copying the soft link from the share:

If you'd like to use the auth lobby to accept, for ease of use like Fission Drive does, then you can create a share link with the share details we got earlier:

Soft links

When sharing a file or directory with someone, they will receive the updates to those items due to how soft links work. Most filesystem methods work out of the box with soft links, such as get and read. But sometimes, you need to resolve them manually, which you can do with fs.resolveSymlink(). If you want to create a soft link manually, you can do that with:

⚠️ For now soft links are read-only.

The Web Native File System (WNFS) is a file system built on top of the InterPlanetary Linked Data model (). Each Webnative user has their own WNFS, and apps store user files and data in it.

Each file system has a public tree and a private tree, much like your macOS, Windows, or Linux desktop file system. The public tree is "live" and publicly accessible on the Internet. The private tree is encrypted so that only the owner can see the contents.

All information (links, data, metadata, etc.) in the private tree is encrypted. Decryption keys are stored so that access to a given directory grants access to all of its subdirectories.

WNFS is structured and functions similarly to a Unix-style file system, with one notable exception: it's a Directed Acyclic Graph (DAG), meaning that a given child can have more than one parent (think symlinks but without the "sym").

Permissions

A Webnative app assumes full access to the file system unless given a permissions object in the configuration, then it assumes authorization to parts of the filesystem will be granted when from another app.

Paths

WNFS uses directory and file paths built from path segments by path functions.

File System Interface

WNFS exposes a POSIX-style interface:

• add: add a file

• cat: retrieve a file

• exists: check if a file or directory exists

• ls: list a directory

• mkdir: create a directory

• mv: move a file or directory

• read: alias for cat

• rm: remove a file or directory

• write: alias for add

Publish

The publish function synchronizes your file system with the Fission API and IPFS. WNFS does not publish changes automatically because it is more practical to batch changes in some cases. For example, a large data set is better published once than over multiple calls to publish.

Returns: CID the updated root CID for the file system.

API Summary

Methods

Methods for interacting with the filesystem all use absolute paths.

The FileContentthat WNFS can store includes FileContentRaw, Blob, string, number, and boolean. FileContentRaw is Uint8Array. In addition, the private file system can store Objects.

add

Adds file content at a given path.

Params:

• path: FilePath required

• content: FileContentrequired

Returns: CID the updated root CID for the file system

Example:

cat

Retrieves some file content at a given path.

Params:

• path: FilePath required

Returns: FileContent

Example:

exists

Checks if there is anything located at a given path.

Params:

• path: DistinctivePath required

Returns: boolean

Example:

get

Retrieves the node at the given path, either a File or Tree object

Params:

• path: DistinctivePath required

Returns: Tree | File | null

Example:

ls

Returns a list of links at a given directory path

Params:

• path: DirectoryPath required

Returns: { [name: string]: Link } Object with the file name as the key and its Link as the value.

Example:

mkdir

Creates a directory at the given path

Params:

• path: DirectoryPath required

Returns: CID the updated root CID for the file system

Example:

mv

Move a directory or file from one path to another.

Params:

• from: DistinctivePath required

• to: DistinctivePath required

Returns: CID the updated root CID for the file system

Example:

rm

Removes a file or directory at a given path.

Params:

• path: DistinctivePath required

Returns: CID the updated root CID for the file system

Example:

write

Alias for add.

Params:

• path: FilePath required

• content: FileContent required

Returns: CID the updated root CID for the file system

Example:

Versioning

Each file and directory has a history property, which you can use to get an earlier version of that item. We use the delta variable as the order index, primarily because the timestamps can be slightly out of sequence due to device inconsistencies.

Debugging

Version

Check the Webnative version.

console.log(wn.VERSION)

Debug Logs

Debug logging can be enabled through the configuration object.

{ ...configuration, debug: true }

When Webnative makes a change to the user's filesystem, it logs:

📓 Adding to the CID ledger

Next, Webnative links the change to make it available across the web.

🌊 Updating your DNSLink

When linking completes, the change is published and available to other browsers.

🪴 DNSLink updated:

Shorthands

A Webnative program provides shorthand utility functions for easy access:

export type ShortHands = {
  loadFileSystem: (username: string) => Promise<FileSystem>
  agentDID: () => Promise<string>
  sharingDID: () => Promise<string>
}

The shorthands include:

• loadFileSystem. Loads the user's file system. Useful when you want to delay loading the filesystem until some time after initialization.

• agentDID. Retrieves the agent DID for the current device.

• sharingDID. Retrieves the sharing DID for the current device.

WNFS File System Roots

WNFS comes with three separate top-level file systems "roots": public, pretty, and private.

Public

Not encrypted. Full metadata support. Starts with /public.

Pretty

Not encrypted. No metadata. Represented simply as /p to be nice and short when creating public URLs like /p/path/to/file.img. It does not support versioning, use the Public or Private trees for that.

Private

Encrypted. Structured so that file metadata as well as contents are obscured. Starts with /private.

Web Worker

Can I use my file system in a web worker? Yes, but depending on which type of session you want you may need to adjust your setup. To be more specific, when working without capabilities you can just create a program in your web worker. But when working with capabilities, it'll depend on how your chosen capabilities flow works. In the case of the current Fission auth lobby, access to the window object is needed when requesting capabilties, so that'll need to happen on the UI/main thread.

Feel free to reach out on our Discord if you need help.

Versions

Since the file system may evolve over time, a "version" is associated with each node in the file system (tracked with semver).

Every Fission App gets a free subdomain.

Currently, these look like YOURUSERNAME.fission.name, but we're migrating to user accounts and attached apps, where every app has YOURAPPNAME.fission.app.

To use a custom domain of your own, like YOURAPPDOMAIN.com, you need to make some changes to DNS. There are two methods detailed in the following pages:

1. Fission Hosted DNS - move your nameservers to Fission, we automate everything

2. Control your own DNS - create a CNAME and TXT record and point them at Fission services

The webnative platform API provides methods to work with Fission apps.

The platform API makes it possible to manage user apps and, combined with the webnative filesystem methods, create and manage apps entirely from the browser.

The API methods are prefixed with apps.

• apps.index: A list of all of your apps and their associated domain names

• apps.create: Creates a new app, assigns an initial subdomain, and sets an asset placeholder

• apps.publish: Publish a new app version

• apps.deleteByDomain: Destroy an app identified by domain

Permissions

Apps that use the platform API must request permission to work with a user's apps. Permissions are requested when a user signs in through the Fission Auth Lobby. See the requesting capabilities guide for more on requesting permissions.

Platform API permissions are requested at permissions.platform.apps in the configuration object.

import * as wn from 'webnative'

const permissions = {
  platform: {
    apps: "*",
  },
  // ... other permissions
}

// Create Webnative program with expected permissions
wn.program({ permissions }).then(program => {
  if (!program.session) {
    // We don't have the permissions yet. 
    // Let's send the user to auth.fission.codes and ask for them:
    program.capabilities.request()
  } else {
    // we're all set up! 🎉
  }
})

The value at permissions.platform.apps can be

• "*": Grant complete app management access for all of the user's apps

• An array of domain names, e.g. [ "an-app.fission.app", "another-app.fission.app" ]: Grant permission to manage specific apps. Those apps can be published or deleted.

Endpoints & Dependencies

These app function are a bit more low level than your usual Webnative functions. This is because these functions are specifically for the Fission architecture, while the rest of Webnative is not. We'll need two things to get started, the endpoints and the dependencies:

const endpoints = wn.fission.PRODUCTION // default, can also be fission.STAGING, depending on your used components
const dependencies = { crypto: program.components.crypto, reference: program.components.reference }

API

apps.index

Lists all user apps and their associated domain names.

Required permissions: { platform: { apps: "*" } } full app management permissions

Params: No parameters

Returns: App[] with the domain names, creation and modification times for each app

Example:

const index = await wn.apps.index(endpoints, dependencies)
// [ 
//   { domains: ['your-fission-deployment.fission.app'],
//     insertedAt: '<creation-time>',
//     modifiedAt: '<last-modified-time>',
//   } 
// ]

apps.create

Creates a new app, assigns an initial subdomain, and publishes a placeholder site.

Required permissions: { platform: { apps: "*" } } full app management permissions

Params:

• subdomain: string | null optional, set to null to generate a name

Returns: { domain: string } the subdomain of the newly created app

Example:

const newApp = await wn.apps.create(endpoints, dependencies, null)
// { domain: 'your-fission-deployment.fission.app' }

apps.publish

Publishes a new app version by IPFS CID. If the app does not exist yet, create the app first with apps.create.

Required permissions: Needs either permission for the app domain or full app management permissions. See Permissions.

Params:

• domain: string required

• cid: CID required

Returns: Nothing returned

Example:

import { decodeCID } from 'webnative/common/cid'

const cid = decodeCID('QmRVvvMeMEPi1zerpXYH9df3ATdzuB63R1wf3Mz5NS5HQN')

await wn.apps.publish(
  endpoints,
  dependencies,
  'your-fission-deployment.fission.app',
  cid
)

Retrieving the CID depends on where you have staged the app code. One convenient way to do this is to publish the app's HTML, CSS, JavaScript, and assets to a public directory in WNFS and retrieve the CID of that directory.

import * as Fission from "webnative/common/fission"
import * as IPFS from "webnative/components/depot/implementation/ipfs/index"
import { namespace } from "webnative"

// Get an IPFS instance
const storage = Webnative.defaultStorageComponent(CONFIG)
const { ipfs } = await IPFS.nodeWithPkg(
  { storage },
  await IPFS.pkgFromCDN(IPFS.DEFAULT_CDN_URL),
  `${Fission.PRODUCTION.server}/ipfs/peers`,
  `${namespace(CONFIG)}/ipfs`,
  false
)

// The POSIX path where you published your app code in the public filesystem:
const appPath = wn.path.directory(
  'Apps',
  'your-fission-deployment'
  'Published'
)

// Get UnixFS CID for public directory
const rootCid = await fs.root.put()
const stats = await ipfs.files.stat(`/ipfs/${rootCid}/p/${wn.path.toPosix(appPath)}`)

// The CID you use to publish with the platform API:
const cid = stats.cid.toString()

// 🚀
await wn.apps.publish(endpoints, dependencies, 'your-fission-deployment.fission.app', cid)

apps.deleteByDomain

Delete an app by domain.

Required permissions: Needs either permission for the app domain or full app management permissions. See Permissions.

Params:

• url: string required

Returns: Nothing returned

Example:

await wn.apps.deleteByDomain(endpoints, dependencies, 'your-fission-deployment.fission.app')

Webnative

Some versions of Webnative require apps to migrate their codebase to address breaking changes. Versions with changes are listed below.

Version 0.35.0

This version of Webnative is a major rewrite. Most apps will only need to update their initialization, permission request, and registration code to use the new APIs.

In previous versions, Webnative was initialized using the initialise or app functions that returned a state object:

// Requires permission from the Fission Auth Lobby
const state = await wn.initialise({
  permissions: {
    app: {
      name: "Winamp",
      creator: "Nullsoft"
    },
  }
})

// Redirect to Auth Lobby to request permission
wn.redirectToLobby(state.permissions)

// Initializes an app with root authority
const state = await webnative.app({ useWnfs: true })

// Register the user after checking the username is valid and available
const { success } = await wn.account.register({ username })

In Webnative 0.35, Webnative is initialized by creating namespaced programs and creating sessions.

Initialize a program with permissions when your app requests capability from the Fission Auth Lobby.

const permissions = {
  app: { creator: "Nullsoft", name: "Winamp" }
}

// Permissions are configured at initialization
const program = await webnative.program({
  namespace: { creator: "Nullsoft", name: "Winamp" },
  permissions
})

// (a) Whenever you are ready to redirect to the lobby to request capabilities 
// call the request function:
program.capabilities.request()

// (b) When you have been redirected back from the lobby and
// your program re-initializes, you will have access to the user session.
session = program.session

Apps with root authority initialize without permissions and use authentication strategies to register users and create sessions:

// Initialize the program
const program = await wn.program({
  namespace: { creator: "Nullsoft", name: "Winamp" }
})

// Register the user after checking the username is valid and available
const { success } = await program.auth.register({ username })
  
// Create a session on success
const session = success ? program.auth.session() : null

In both cases, the program will have an authenticated session at initialization when a user returns for another visit.

See the Initialization, Session, Requesting Capabilities, and Authentication Strategies sections for more details on the new APIs.

Webnative 0.35 also updates the file system interface so that only Uint8Array can be written to and read from WNFS. If you are storing strings or other types of data, you will need to convert them Uint8Array before writes and convert them from Uint8Array on reads.

For example, writing a string to a file and later reading it looks like this:

// Create a sub directory and add some content
const contentPath = wn.file(
  Branch.Private, "Sub Directory", "hello.txt"
)

await fs.write(
  contentPath,
  new TextEncoder().encode("👋") // Uint8Array
)

// Persist changes and announce them to your other devices
await fs.publish()

// Read the file
const content = new TextDecoder().decode(
  await fs.read(contentPath)
)

Please review the CHANGELOG for an overview of the other changes in this version.

Version 0.28.0

The publicReadKey function in keystore-idb was renamed topublicExchangeKey.

Most users will not need to change anything for webnative 0.28.0, unless they are interacting directly with keystore-idb.

Version 0.27.0

The type of App returned app.index has changed. Previously, the return type was

export type App = {
  domain: string
}

In Webnative 0.27.0, the the return type is

export type App = {
  domains: string[]
  insertedAt: string
  modifiedAt: string
}

The domain for the app is now in the domains array.

Version 0.26.1

The URL for loading webnative from UNPKG has changed. In Webnative 0.26.0, Webnative was available as index.min.js.

<script src="https://unpkg.com/webnative@0.26.0/dist/index.min.js"></script>

We found that some projects needed the UMD build and brought it back in Webnative 0.26.1. We have replaced index.min.js with index.umd.min.js.

<script src="https://unpkg.com/webnative@0.26.1/dist/index.umd.min.js"></script>

Version 0.26.0

The URL for loading webnative from UNPKG has changed. In previous versions, Webnative was available as index.umd.js.

<script src="https://unpkg.com/webnative@latest/dist/index.umd.js"></script>

In Webnative 0.26, Webnative is available as index.min.js.

<script src="https://unpkg.com/webnative@0.26.0/dist/index.min.js"></script>

Version 0.24

The way paths are used throughout the Webnative and filesystem APIs has changed.

In earlier versions of Webnative, API calls expected UNIX style paths.

const bool = await fs.exists("private/some/file")
const updatedCID = await fs.mkdir("public/some/directory")

In Webnative 0.24, paths are created by path helper functions for files and directories.

const bool = await fs.exists(wn.path.file("private", "some", "file"))
const updatedCID = await fs.mkdir(wn.path.directory("public", "some", "directory"))

The docs for the previous API remain available for reference.

This guide is versioned by Fission CLI/Webnative SDK versions. You can switch versions at the top left of the UI above the Overview to match the CLI or SDK version you are using.

The Latest version represents all versions newer than the last numbered version. We add a new guide version when a breaking change occurs in the CLI or Webnative

We can take care of this for you by hosting your DNS for you. This means changing your name servers to the Fission ones. Below are guides for some DNS providers.

Fission Nameservers

• ns1.fission.systems

• ns2.fission.systems

• ns3.fission.systems

• ns4.fission.systems

Once this is completed, we'll confirm it and handle any other updates needed automatically.

Changing Nameservers in Namecheap

Go to the domain you want to host on Fission in your Namecheap admin:

Where it says "Namecheap BasicDNS", select "Custom DNS" from the drop down:

Enter in ns1.fission.systems and ns2.fission.systems and click the green check mark to save.

By adding a TXT record for your app and a CNAME pointing at our gateway, you can run your DNS elsewhere but still have a custom domain for your Fission app.

Add a CNAME pointing to ipfs.runfission.com

For your domain, YOURAPPDOMAIN.com, go into your DNS provider control panel and add a CNAME pointing to ipfs.runfission.com.

The process for a subdomain is the same SUB.YOURAPPDOMAIN.com, but looks a little different. Go into your DNS provider control panel and add a CNAME pointing to ipfs.runfission.com.

Add a TXT record with dnslink

Next, add a TXT record pointing to your app subdomain. Your APPNAME is created when you run fission app register, and will look something like junior-angular-tulip . We're creating a link to say that the content from your app should be served up your domain with a special dnslink record:

Subdomains function the same way, with the _dnslink subdomain, where you're adding the TXT record being "above" the SUB.YOURDOMAIN.com record, which looks like this:

Get in touch to complete the process

This process is not fully automated right now, so you'll need to send us an email support@fission.codes or drop by our support page to send us a chat, and we can get things setup on our end.

Fission logos and badges are copyrighted by our company, Fission Internet Software. Feel free to use them in apps that use our software or when linking to us.

Please do not modify these logos or brands. Let us know if you need another format for your use case.

Basic example of how to make a UCAN. Note that the issuer always has to be your DID, because the UCAN will be signed with your private key.

By using Cloudflare as your DNS provider and their , you can deploy on Fission but have your content be served by Cloudflare. This will let you use custom domains with your Fission apps while we work to automate the process fully on the platform.

Add a CNAME pointing to Cloudflare's IPFS gateway

For your domain, YOURAPPDOMAIN.com, go into your DNS provider control panel and add a CNAME pointing to cloudflare-ipfs.com.

Since your domain is already hosted with Cloudflare, there's no step two: they'll add SSL support to it automatically, and turn off proxying.

Add a TXT record with dnslink

Now, add a TXT record pointing to your app subdomain. Your APPNAME is created when you run fission app register, and will look something like junior-angular-tulip . We're creating a link to say that the content from that app should be served up at your domain with a special dnslink record:

That's it, you're done!

Whenever you publish a new version of your Fission app, we update the hash that this special record points to. When you go to YOURAPPDOMAIN.com, Cloudflare's gateway looks up this _dnslink record, checks the ipns record, gets the hash, and fetches the content from the global IPFS network. This might even be from your computer directly.

We're developing a series of example apps, base templates, and code examples to help you get up to speed in building Fission-powered apps. The is also a great place to look for inspiration.

Elm

The Quotes app is a simple app written in Elm. It features Fission login, and stores quotes data in your personal storage.

• Try it live at

• Browse the source on Github

Fission Drive is maintained by the Fission team and included with every Fission account. It lets you work with all of the files in your account's file system.

• Read more about

• Login at

• Browse the source on Github

WebAssembly

, and also teaches you about using WebAssembly.

React

Photo Gallery

Storing WebAssembly Modules

In this guide, we will show how to store WebAssembly modules in Fission web native storage. Our goal will be to store a WASM module and execute it at a later time.

The code in this guide is available in the repository and the example is published at .

We have compiled an add function from C to a WASM module.

Our example app will make a GET request for add.wasm and store it in web native storage. We will list the contents of the directory where the module is stored to confirm it is there. Finally, we will load the module from storage and add some numbers!

Authenticate the user

Before we can store a WASM module, we need to initialize webnative and ask the user for permission to use their web native file system. This example asks for permission to use app storage and uses fs as an alias for the file system after we initialize.

We pass fissionInit to webnative and get back a state that tells us if the user has authenticated or not.

In the AuthSucceeded and Continuation cases, the user gave our app permission to use their file system. Otherwise, they have not been asked or they declined.

The user may have already stored add.wasm and used it to add numbers on a previous visit, so we check and display a stored result if we have one.

If the user has not authenticated, we show them a Sign In button that will redirect them to the Fission auth lobby.

Request and store the module

After authentication, we are ready to request add.wasm and store it in web native storage.

We fetch add.wasm and stream the Response into an ArrayBuffer. It will be stored as a Blob in app storage at the path wasm/math/add.wasm.

We prepare a path and blob, write the blob to the local file system, and publish it to the user's wider file system across the web. After we publish, the module is available on any device where the user has set up web native storage.

List directory contents

Next, we can check to make sure the module has been saved in storage.

This time we prepare a wasm/math path for the directory and call fs.ls to list its contents. We take each entry in the directory listing and append its metadata to a table.

Each entry has a name, size (in bytes), last modified time, and a flag indicating whether it is a file or directory.

Load and use the module

The module is in storage and we are ready to use it! Each time a user submits lhs and rhs numbers, we load add.wasm and add their numbers.

After some input validation, we prepare the wasm/math/add.wasm path, make sure a module exists at that path, and read it into a buffer. We instantiate the WASM module and call the add function off it.

Earlier we mentioned that storing the module makes it available across the web. Why not do the same for our result? We store the result at the path results/add, and now both the module and the last result are available on any device!

Deleting the module and result

We can delete the module and result from storage to reset our example.

We prepare paths for the module and result and use fs.rm to delete them. Lastly, we publish the deletion to remove them from the wider file system.

Store once, compute once

Storing WASM modules and results means you only need to request a module or perform a computation once. The web native file system will sync modules and results across user devices automatically. This opens up many opportunities to simplify your applications and sync app data across user devices.

Reading this guide gives you a taste of how this all works, but extending this example will take you much further! Here are a couple of suggested exercises that will help you to get started with web native.

• Distributed addition. How about instead of overwriting the result of an addition, we keep a running total across devices?

• Build a calculator. A bit more ambitious, but a calculator app that stores state across devices would be so cool!