gun README

The project's README from github.com/amark/gun. As one markdown file: README.md.

Build Gitter

GUN is an ecosystem of tools that let you build community run and encrypted applications - like an Open Source Firebase or a Decentralized Dropbox.

The Internet Archive and 100s of other apps run GUN in-production.

Decentralized alternatives to Zoom, Reddit, Instagram, Slack, YouTube, Stripe, Wikipedia, Facebook Horizon and more have already pushed terabytes of daily P2P traffic on GUN. We are a friendly community creating a free fun future for freedom:

Quickstart

GUN is super easy to get started with:

Note: If you don't have node or npm, read this first. If the npm command line didn't work, you may need to mkdir node_modules first or use sudo.

<script src="https://cdn.jsdelivr.net/npm/gun/gun.js"></script>
<script>
// import GUN from 'gun'; // in ESM
// GUN = require('gun'); // in NodeJS
// GUN = require('gun/gun'); // in React
gun = GUN();

gun.get('mark').put({
  name: "Mark",
  email: "[email protected]",
});

gun.get('mark').on((data, key) => {
  console.log("realtime updates:", data);
});

setInterval(() => { gun.get('mark').get('live').put(Math.random()) }, 9);
</script>

cat = {name: "Fluffy", species: "kitty"};
mark = {boss: cat};
cat.slave = mark;

// partial updates merge with existing data!
gun.get('mark').put(mark);

// access the data as if it is a document.
gun.get('mark').get('boss').get('name').once(function(data, key){
  // `once` grabs the data once, no subscriptions.
  console.log("Mark's boss is", data);
});

// traverse a graph of circular references!
gun.get('mark').get('boss').get('slave').once(function(data, key){
  console.log("Mark is the cat's slave!", data);
});

// add both of them to a table!
gun.get('list').set(gun.get('mark').get('boss'));
gun.get('list').set(gun.get('mark'));

// grab each item once from the table, continuously:
gun.get('list').map().once(function(data, key){
  console.log("Item:", data);
});

// live update the table!
gun.get('list').set({type: "cucumber", goal: "jumping cat"});

Want to keep building more? Jump to THE DOCUMENTATION!

About

First & foremost, GUN is a community of the nicest and most helpful people out there. So I want to invite you to come tell us about what you are working on & wanting to build (new or old school alike! Just be nice as well.) and ask us your questions directly. :)


Watch the 100 second intro!

The GUN ecosystem stack is a collection of independent and modular tools covering everything from CRDT conflict resolution, cryptographic security & encryption, radix storage serialization, mesh networking & routing algorithms, to distributed systems correctness & load testing, CPU scheduled JSON parser to prevent UI lag, and more!

On that note, let's get some official shout outs covered first:

Support

Thanks to:

              

Robert Heessels, Lorenzo Mangani, NLnet Foundation, Sam Liu, Daniel Dombrowsky, Vincent Woo, AJ ONeal, Bill Ottman, Mike Lange, Sean Matheson, Alan Mimms, Dário Freire, John Williamson, Robin Bron, Elie Makhoul, Mike Staub, Bradley Matusiak, Jeff Cook, Nico, Aaron Artille, Tim Robinson, Fabian Stamm, Mike Staub, Hunter Owens, Jacob Millner, Gerrit Balindt, Gabriel Lemon, Murage Martin, Jason Stallings

History

GUN was created by Mark Nadal in 2014 after he had spent 4 years trying to get his collaborative web app to scale up with traditional databases.

After he realized Master-Slave database architecture causes one big bottleneck, he (as a complete newbie outsider) naively decided to question the status quo and shake things up with controversial, heretical, and contrarian experiments:

The NoDB - no master, no servers, no "single source of truth", not built with a real programming language or real hardware, no DevOps, no locking, not just SQL or NoSQL but both (all - graphs, documents, tables, key/value).

The goal was to build a P2P database that could survive living inside any browser, and could correctly sync data between any device after assuming any offline-first activity.

Technically, GUN is a graph synchronization protocol with a lightweight embedded engine, capable of doing 20M+ API ops/sec in just ~9KB gzipped size.

Documentation

API reference

Tutorials

Examples

GraphQL

Electron

React & Native

Vue

Svelte

Webcomponents

CAP Theorem Tradeoffs

How Data Sync Works

How GUN is Built

Crypto Auth

Modules

Roadmap

This would not be possible without community contributors, big shout out to:

ajmeyghani (Learn GUN Basics with Diagrams); anywhichway (Block Storage); beebase (Quasar); BrockAtkinson (brunch config); Brysgo (GraphQL); d3x0r (SQLite); forrestjt (file.js); hillct (Docker); JosePedroDias (graph visualizer); JuniperChicago (cycle.js bindings); jveres (todoMVC); kristianmandrup (edge); Lightnet (Awesome Vue User Examples & User Kitchen Sink Playground); lmangani (Cytoscape Visualizer, Cassandra, Fastify, LetsEncrypt); mhelander (SEA); omarzion (Sticky Note App); PsychoLlama (LevelDB); RangerMauve (schema); robertheessels (gun-p2p-auth); rogowski (AXE); sbeleidy; sbiaudet (C# Port); Sean Matheson (Observable/RxJS/Most.js bindings); Shadyzpop (React Native example); sjones6 (Flint); RIP Stefdv (Polymer/web components); zrrrzzt (JWT Auth); xmonader (Python Port);

I am missing many others, apologies, will be adding them soon! This list is infinitely old & way out of date, if you want to be listed in it please make a PR! :)

Testing

You will need to npm install -g mocha first. Then in the gun root folder run npm test. Tests will trigger persistent writes to the DB, so subsequent runs of the test will fail. You must clear the DB before running the tests again. This can be done by running rm -rf *data* command in the project directory.

Shims

These are only needed for NodeJS & React Native, they shim the native Browser WebCrypto API.

If you want to use SEA for User auth and security, you will need to install:

npm install @peculiar/webcrypto --save

Please see our React Native docs for installation instructions!

Then you can require SEA without an error:

GUN = require('gun/gun');
SEA = require('gun/sea');

Deploy

Note: The default examples that get auto-deployed on npm start CDN-ify all GUN files, modules, & storage.

Note: Moving forward, AXE will start to automatically cluster your peer into a shared DHT. You may want to disable this to run an isolated network.

Note: When deploying a web application using GUN on a cloud provider, you may have to set CI=false in your .env. This prevents GUN-specific warnings from being treated as errors when deploying your app. You may also resolve this by modifying your webpack config to not try to build the GUN dependencies.

To quickly spin up a GUN relay peer for your development team, utilize Heroku, Docker, or any others listed below. Or some variant thereof Dokku, K8s, etc. ! Or use all of them so your relays are decentralized too!

Linux

SSH into the home directory of a clean OS install with sudo ability. Set any environment variables you need (see below), then do:

curl -o- https://raw.githubusercontent.com/amark/gun/master/examples/install.sh | bash

Read install.sh first! If curl is not found, copy&paste the contents of install.sh into your ssh.

You can now safely CTRL+A+D to escape without stopping the peer. To stop everything killall screen or killall node.

Environment variables may need to be set like export HTTPS_CERT=~/cert.pem HTTPS_KEY=~/key.pem PORT=443. You can also look at a sample nginx config. For production deployments, you probably will want to use something like pm2 or better to keep the peer alive after machine reboots.

Dome

Deploy GUN in one-click with Dome and receive a free trial:

Deploy to Dome

Heroku

Deploy

Heroku deletes your data every 15 minutes, one way to fix this is by adding cheap storage.

Or:

git clone https://github.com/amark/gun.git
cd gun
heroku create
git push -f heroku HEAD:master

Then visit the URL in the output of the 'heroku create' step, in a browser. Make sure to set any environment config vars in the settings tab.

Zeet.co

Deploy

Then visit the URL in the output of the 'now --npm' step, in your browser.

Docker

Warning: Docker image is community contributed and may be old with missing security updates, please check version numbers to compare.

Docker Automated build Docker Pulls Docker Stars

Pull from the Docker Hub . Or:

docker run -p 8765:8765 gundb/gun

Or build the Docker image locally:

git clone https://github.com/amark/gun.git
cd gun
docker build -t myrepo/gundb:v1 .
docker run -p 8765:8765 myrepo/gundb:v1

Or, if you prefer your Docker image with metadata labels (Linux/Mac only):

npm run docker
docker run -p 8765:8765 username/gun:git

Then visit http://localhost:8765 in your browser.

License

Designed with ♥ by Mark Nadal, the GUN team, and many amazing contributors.

Openly licensed under Zlib / MIT / Apache 2.0.

FOSSA Status

YouTube . Twitter

gun (amark/gun)

Searching Database…

19.1K ·GitHub
Gun
What is this?GUN is an open source cybersecurity protocol for syncing decentralized graph data — a peer-to-peer database that keeps app data in sync across browsers and devices, with no master server and no single source of truth.
So is it a server I have to host, or a library I add to my code?A JavaScript library with a lightweight embedded engine that you drop into a browser or Node app; devices then sync peer-to-peer. Running a relay peer is optional, mainly so a team's data stays reachable when individual peers are offline.
How do I try it out?Fastest path: the interactive tutorial in the browser (about 5 minutes for the average developer). For local development run npm install gun, then cd node_modules/gun && npm start to launch the examples.
Do I need Node, or can I just open a browser?The tutorial runs entirely in a browser with nothing to install. For local development you need Node and npm; the package's only direct dependency is the ws WebSocket package, which npm pulls in automatically.
Are there any gotchas when deploying it?A few: Heroku wipes your data every 15 minutes unless you attach storage, the community Docker image may be old and missing security updates, and some cloud builds need CI=false in .env so GUN's warnings aren't treated as build errors.
What happens when a device goes offline?That's the core design assumption: GUN is offline-first — it expects devices to disconnect and then syncs their data correctly once they reconnect, resolving conflicts with CRDTs.
Why did the author build GUN instead of using a traditional database?Mark Nadal spent 4 years trying to scale a collaborative web app on traditional databases and concluded that Master-Slave architecture creates one big bottleneck. In 2014 he started the NoDB experiment: no master, no servers, no single source of truth — a P2P database that can live inside any browser and sync across devices offline-first.
Is it a document store, a table store, or a graph database?All of them: the core is a graph, but the same data works as documents, tables, or key/value — the project calls it not just SQL or NoSQL but both. Circular references between documents are supported too.
How fast is it, and how heavy?The engine claims 20M+ API ops/sec at roughly 9KB gzipped. It even uses a CPU-scheduled JSON parser so parsing doesn't cause UI lag.
Does it handle user accounts and encryption?Yes — SEA is GUN's module for user auth and security, built on cryptographic encryption. In browsers it uses the native WebCrypto API; in Node or React Native you first install the @peculiar/webcrypto shim.
What are similar projects?yjs, anoma, DeFiBridgeDiamond, rxdb, shardeum, diem, sphere-sdk, surrealdb
Which topics is it in?crdt, mesh-network, embedded-database, graph-database, dapp, key-value, crypto, sync, graph, realtime, big-data, nosql
Creator
amark
Size
32.2 MB
Stars
19.1K
Updated
CommitOct 15Release0.2019.413Apr 15
Age
12y
Commits · 90 Days