diff --git a/README.md b/README.md index fc1788b21e..56f925ea43 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,7 @@ See [how it works](https://sandstorm.io/how-it-works) and [security practices](h ## How to Package Apps -See [the packaging tutorial in the Sandstorm documentation](https://docs.sandstorm.io/en/latest/vagrant-spk/packaging-tutorial/). +See [the developer portal in the Sandstorm documentation](https://docs.sandstorm.io/en/latest/developing/). ## Contribute diff --git a/docs/developing.md b/docs/developing.md index 9fce47f32d..3fdc71ce9f 100644 --- a/docs/developing.md +++ b/docs/developing.md @@ -1,46 +1,76 @@ -# Developing on Sandstorm - -Sandstorm can run any web app that can run on Linux so long as the -code and all the dependencies have been bundled into an SPK file. -Anyone can make a Sandstorm package (SPK), such as the author of a -program or someone wants to run the app on their own Sandstorm -server. - -If you haven't yet, now is a good time to try the Sandstorm demo! -Work through the [guided tour](guided-tour.md). - +Here in the **Sandstorm developer portal**, you will find to resources that help people build new +apps on top of Sandstorm, package existing apps, and understand how apps and Sandstorm fit together. + +
+
New? Try tutorial
+
Why Sandstorm
+
Community Q&A
+
See app market
+
Live chat via IRC
+
Try a demo app
+
+ + +Sandstorm apps can be in **any language** so long as it runs on Linux (PHP, Python, Node.js, Ruby, +etc.). The app bundles its dependencies so it runs in a consistent environment. Sandstorm handles +user management and mitigates [95% of security issues](using/security-non-events.md). App authors +don't have to run servers since users run your app on their own servers. Sandstorm's "grain" model +allows developers to rely on Sandstorm for supporting multiple instances/documents rather than +writing that code in the app. Read more on the [developer features +page](https://sandstorm.io/developer). ## Creating an app package -* **Tutorial**: [Five minute packaging tutorial](vagrant-spk/packaging-tutorial.md) -* **Conceptual overview**: [App Developer Handbook](developing/handbook.md) -* **Language support**: [Platform stacks for Meteor, Python, PHP](vagrant-spk/platform-stacks.md) | [Other](vagrant-spk/platform-stacks.md#diy-platform-stack) -* **Code & service dependencies**: [Code dependencies](vagrant-spk/code-dependencies.md) | [MySQL](vagrant-spk/services.md#mysql) | [Other databases & services](vagrant-spk/services.md#other-services) -* **Troubleshooting**: [Package troubleshooting](developing/troubleshooting.md) -* **vagrant-spk in depth**: [Installation](vagrant-spk/installation.md) | [Original design](vagrant-spk/design.md) | [Customizing & understanding vagrant-spk](vagrant-spk/customizing.md) +- **Tutorial**: [Five minute packaging tutorial](vagrant-spk/packaging-tutorial.md) +- **What makes a great Sandstorm app**: [App Developer Handbook](developing/handbook.md) +- **Language support**: [Platform stacks for Meteor, Python, PHP, Node.js](vagrant-spk/platform-stacks.md) | [Other](vagrant-spk/platform-stacks.md#diy-platform-stack) +- **Code & service dependencies**: [Code dependencies](vagrant-spk/code-dependencies.md) | [MySQL](vagrant-spk/services.md#mysql) | [Other databases & services](vagrant-spk/services.md#other-services) +- **Troubleshooting**: [Package troubleshooting](developing/troubleshooting.md) +- **vagrant-spk in depth**: [Installation](vagrant-spk/installation.md) | [Customizing & understanding vagrant-spk](vagrant-spk/customizing.md) | [Initial design document](vagrant-spk/design.md) --- -## Sandstorm for systems engineers +## How to leverage the community + +The Sandstorm ecosystem is full of people who want to promote your app, give you feedback, and use +it. + +- **Free services from Sandstorm core team**: [Free Oasis service for app authors](https://sandstorm.io/news/2016-02-05-app-author-publicity-oasis) +- **Getting help**: [Community feedback and Q&A](https://groups.google.com/d/forum/sandstorm-dev) | [Real-time IRC chat on freenode](https://kiwiirc.com/client/irc.freenode.net/?channel=#sandstorm) | [Watch presentations on the Sandstorm YouTube channel](https://www.youtube.com/channel/UC8xKZRW86Fa9W00uAppBXXg) | [Email the core team](mailto:community@sandstorm.io) +- **Publicity**: [Free icon design for your app](https://sandstorm.io/news/2015-11-10-icons-spks-for-everyone) | [Give a meetup/conference talk about your app](https://sandstorm.io/news/2015-12-17-community-talks) | [Public demo service for all Sandstorm apps](https://sandstorm.io/news/2015-02-06-app-demo) | [General publicity help](https://sandstorm.io/news/2016-02-05-app-author-publicity-oasis) +- **Read more**: [All community resources](https://sandstorm.io/community) + +--- + +## All about grains + +When a user runs an app within Sandstorm, they create one or more _grains_ of the app. +Read about how grains work and how they affect your app. + +- **Grain URLs and the grain-frame**: [URLs, domain names, page titles](developing/path.md) +- **Sandstorm system architecture**: [How Sandstorm works](using/how-it-works.md) | [Grain isolation and other security practices in Sandstorm](using/security-practices.md) +- **How to choose the granularity for your app**: [] + +--- + +## App sharing, publishing, & permission levels -You might enjoy learning how Sandstorm is put together. +Each app instance (aka "grain") is private by default to the user who +created it. Read these documents to learn how access control works. -* **Technical summary**: [How Sandstorm works](using/how-it-works.md) -* **Minimalist packaging**: [Raw SPK packaging guide](developing/raw-packaging-guide.md) -* **Raw packaging & integration guides**: [Python](developing/raw-python.md) | [Ruby on Rails](developing/raw-ruby-on-rails.md) | [Pure client apps](developing/raw-pure-client-apps.md) -* **Security**: [Security Practices Overview](using/security-practices.md) +- **Login & permissions**: [User authentication & permissions](developing/auth.md) +- **Making content accessible outside Sandstorm**: [Publishing static content, including to the user's domain](developing/web-publishing.md) | [Exporting HTTP APIs for mobile, desktop, Javascript clients](developing/http-apis.md) +- **Further reading**: [Delegation is the Cornerstone of Civilization](https://blog.sandstorm.io/news/2015-05-05-delegation-is-the-cornerstone-of-civilization.html) --- @@ -50,35 +80,38 @@ By default, Sandstorm runs each app instance with no network access. Read these documents to configure an app to get access to services on the Internet or to each other. -* **Supported protocol**: [SMTP (email)](developing/email-from-apps.md) -* **Other protocols**: Work in progress. -* **Inter-app communication**: Work in progress. +- **Supported protocol**: [SMTP (email)](developing/email-from-apps.md) +- **Other protocols**: Work in progress. +- **Inter-app communication**: Work in progress. --- -## App sharing, publishing, & permission levels +## Raw Sandstorm packaging -Each app instance (aka "grain") is private by default to the user who -created it. Read these documents to learn how access control works. +Most Sandstorm packages use [sandstorm-http-bridge](using/how-it-works.md) and +[vagrant-spk](vagrant-spk/customizing.md). However, these tools are independent +and optional. -* **Overview**: [Delegation is the Cornerstone of Civilization](https://blog.sandstorm.io/news/2015-05-05-delegation-is-the-cornerstone-of-civilization.html) -* **Login & permissions**: [User authentication & permissions](developing/auth.md) -* **Making it world-accessible**: [Publishing to the user's domain](developing/web-publishing.md) | [Exporting HTTP APIs](developing/http-apis.md) +- **Minimalist packaging**: [Raw SPK packaging guide](developing/raw-packaging-guide.md) +- **Raw packaging & integration guides**: [Python](developing/raw-python.md) | [Ruby on Rails](developing/raw-ruby-on-rails.md) | [Pure client apps](developing/raw-pure-client-apps.md) --- -## Integrating various languages & libraries into raw Sandstorm +## Raw Sandstorm APIs: Cap'n Proto -If you are curious how to integrate various languages & libraries with -Sandstorm's raw APIs and raw SPK packaging, read these documents. +To make components easier to isolate while retaining high performance, most communication in +Sandstorm occurs using Cap'n Proto. Cap'n Proto files in the Sandstorm source repository contain +useful design or implementation details. Note that Sandstorm typically depends on the **unreleased +git master** of capnproto. Configuration files such as `sandstorm-pkgdef.capnp` use Cap'n Proto as +their file format. -**Note** that most app developers will have an easier time using `vagrant-spk`. This is intended +- **Overview**: [Cap'n Proto website](https://capnproto.org/) | [How Cap'n Proto makes Sandstorm more secure](https://sandstorm.io/news/2014-12-15-capnproto-0.5) +- **Example**: [Explanation of how drivers will work, found within ip.capnp](https://github.com/sandstorm-io/sandstorm/blob/master/src/sandstorm/ip.capnp) +- **Cap'n Proto implementations**: [C++, Erlang, Go, Javascript, Python, Rust, and others](https://capnproto.org/otherlang.html) +- **Further reading**: [A list of all Cap'n Proto files in the source repository](https://github.com/sandstorm-io/sandstorm/search?l=cap%27n-proto&p=2&q=type%3Acapnp+&utf8=%E2%9C%93) --- -## Further reference documentation +## Documentation on how to contribute to Sandstorm -We call Sandstorm a _platform_ because it provides concepts, -capabilities, and APIs that apps can use. The documentation about -further concepts may be found on our [GitHub -wiki](http://github.com/sandstorm-io/sandstorm/wiki). +To find out how to contribute to Sandstorm, read the [wiki on GitHub](https://github.com/sandstorm-io/sandstorm/wiki). diff --git a/docs/extra.css b/docs/extra.css index 77ce0d67f3..d86168e2c3 100644 --- a/docs/extra.css +++ b/docs/extra.css @@ -39,3 +39,44 @@ float: none; vertical-align: middle; } + +.developer-next-steps { + display: flex; + flex-wrap: wrap; + justify-content: center; + align-items: center; + /* Like the default paragraph styling */ + margin-bottom: 24px; +} + +.next-step { + max-width: 25%; + text-align: center; + min-width: 140px; +} +.next-step::before { + background-size: 100px 100px; + background-repeat: no-repeat; + background-position: center top; + height: 100px; + content: " "; + display: block; +} +.next-step.tutorial::before { + background-image: url("https://sandstorm.io/images/help-package.svg"); +} +.next-step.why::before { + background-image: url("https://sandstorm.io/images/help-share.svg"); +} +.next-step.discussion::before { + background-image: url("https://sandstorm.io/images/help-write.svg"); +} +.next-step.app-market::before { + background-image: url("https://sandstorm.io/images/core-apps-growing.svg"); +} +.next-step.live-chat::before { + background-image: url("https://sandstorm.io/images/help-discuss.svg"); +} +.next-step.demo-app::before { + background-image: url("https://sandstorm.io/images/core-single-sign-on.svg"); +} diff --git a/docs/vagrant-spk/customizing.md b/docs/vagrant-spk/customizing.md index b116ef8aa9..b7582caa39 100644 --- a/docs/vagrant-spk/customizing.md +++ b/docs/vagrant-spk/customizing.md @@ -1,5 +1,12 @@ # Customizing and understanding vagrant-spk +## Overview of vagrant-spk + +The goal of `vagrant-spk` is to be an easy-to-install tool that runs on +Windows, Mac, and Linux that lets people create Sandstorm packages +without mucking with their main operating system. It works properly +on Mac, GNU/Linux, and Windows systems. + ## What the files are for `vagrant-spk` will create a `.sandstorm/` folder in your repo and set up some files with some defaults for your app stack. You will likely need to modify diff --git a/docs/vagrant-spk/index.md b/docs/vagrant-spk/index.md index 61e810b254..e69de29bb2 100644 --- a/docs/vagrant-spk/index.md +++ b/docs/vagrant-spk/index.md @@ -1,11 +0,0 @@ -# vagrant-spk - -The goal of `vagrant-spk` is to be an easy-to-install tool that runs on -Windows, Mac, and Linux that lets people create Sandstorm packages -without mucking with their main operating system. - -Right now it works properly on Mac and GNU/Linux systems. Windows -support is forthcoming. - -Use the navigation at the top of the screen to navigate the -`vagrant-spk` documentation. diff --git a/docs/vagrant-spk/packaging-tutorial.md b/docs/vagrant-spk/packaging-tutorial.md index 512f14870e..0170b88c30 100644 --- a/docs/vagrant-spk/packaging-tutorial.md +++ b/docs/vagrant-spk/packaging-tutorial.md @@ -3,7 +3,9 @@ Style: Hands-on introductory tutorial. This tutorial will show you how to package an app for -[Sandstorm](https://sandstorm.io) in five minutes. Going through +[Sandstorm](https://sandstorm.io) in five minutes. (Sometimes the +downloads can take up to 30 minutes, but the interactive time is about +five minutes. Any slow steps are labeled accordingly.) Going through this tutorial, you'll learn: * How to take an existing web application and turn it into a Sandstorm diff --git a/mkdocs.yml b/mkdocs.yml index 06a0a29b51..a41171d2aa 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -16,8 +16,7 @@ pages: - "Security practices": "using/security-practices.md" - "Security non-events": "using/security-non-events.md" - Developing apps: - - "Overview": "developing.md" - - "Overview of vagrant-spk": "vagrant-spk/index.md" + - "Developer portal": "developing.md" - "Installing vagrant-spk for package dev": "vagrant-spk/installation.md" - "Packaging tutorial": "vagrant-spk/packaging-tutorial.md" - "Packaging tutorial (Meteor)": "vagrant-spk/packaging-tutorial-meteor.md" @@ -25,7 +24,7 @@ pages: - "App developer handbook": "developing/handbook.md" - "User authentication & permissions": "developing/auth.md" - "URLs, domain names, page titles": "developing/path.md" - - "Understanding & customizing": "vagrant-spk/customizing.md" + - "Understanding & customizing vagrant-spk": "vagrant-spk/customizing.md" - "Platform stacks": "vagrant-spk/platform-stacks.md" - "Code dependencies": "vagrant-spk/code-dependencies.md" - "Service dependencies": "vagrant-spk/services.md"