setup

developers/get-started.qmd

@@ -13,3 +13,152 @@ Creating your own, or your own organization's, R-universe creates a showcase of
 R-universe build binaries TODO add details
 
 ## How to set up your universe
+
+Creating a universe for your R packages can be done in a few steps:
+
+1. Create a git repository named (all lowercase) <your-username>.r-universe.dev on your GitHub account, containing a `packages.json` file which lists the git repositories with R packages to include. For an organization at `github.com/ropensci` the repository is thus `github.com/ropensci/ropensci.r-universe.dev`; similarly for an user at `github.com/jeroen` the repository is `github.com/jeroen/jeroen.r-universe.dev`.
+1. Install the [r-universe app](https://github.com/apps/r-universe/installations/new) on this same GitHub account or organization for which you want to create the universe. Clicking on the [app link](https://github.com/apps/r-universe/installations/new) will lead you to a page that asks "Where do you want to install R-universe?".
+1. Wait for your packages to start appearing on https://<yourname>.r-universe.dev once they have finished building.
+1. Document how to install packages from R-universe in the docs of your packages.
+
+A few more details on each step below.
+
+### Creating your personal r-universe subdomain
+
+In R-universe, every user has a private subdomain, where you control the content, and which does not interfere with other users. 
+The subdomains are tied to the GitHub account or organization with that name. 
+
+#### Case-sensitivity
+
+Domain names are by definition case-insensitive and lowercased.
+
+#### How much GitHub is compulsory?
+
+Hence, in order to start a universe you need a GitHub account. 
+However the R packages themselves do not necessarily need to exist under that same account. 
+They don’t even need to be on GitHub: they may be hosted on any public git server. 
+If your R packages are hosted on another git service, such as Gitlab, or a university git server, you can simply use a GitHub account only for publishing a `packages.json` registry for that username, without having to buy into the full GitHub platform.
+
+### Populating the packages.json registry file
+
+In order to publish content on r-universe, you need to create a registry file called [packages.json](https://github.com/maelle/maelle.r-universe.dev/blob/main/packages.json), which lists the git urls containing the R packages you want to include in your universe. The file is formatted as a JSON array with required fields `package` and `url` for each entry, for example:
+
+```json
+[
+    {
+        "package": "curl",
+        "url": "https://github.com/jeroen/curl"
+    },
+    {
+        "package": "pdftools",
+        "url": "https://github.com/ropensci/pdftools"
+    },
+    {
+        "package": "stringdist",
+        "url": "https://github.com/markvanderloo/stringdist",
+        "subdir": "pkg"
+    }
+]
+```
+
+### tracking custom branches or releases
+
+By default, R-universe tracks and builds the default branch for each package git repository, for instance `master` or `main`. 
+It is possible to customize which git branch or tag to track by adding a `branch` field to the registry.
+
+The `branch` field can take the name of any git reference (either a branch or a tag). 
+You can also set it to a special value `"*release"` which will automatically lookup the most recent GitHub release, using [the same syntax](https://cran.r-project.org/web/packages/remotes/vignettes/dependencies.html) as in remotes. 
+For example:
+
+```json
+[
+  {
+    "package" : "somepackage",
+    "url" : "https://github.com/jeroen/somepackage",
+    "branch" : "stable"
+  }
+  {
+    "package": "jose",
+    "url": "https://github.com/jeroen/jose",
+    "branch" : "*release"
+  }
+]
+```
+
+If you want to use the default git branch, it is safest to omit the `branch` field. 
+This way everything will keep working, even if the default branch gets another name at some point in the future.
+
+
+### Hand-written or programmatically created
+
+You can either hand-write this `packages.json` file, or programmatically create it using the tools of your choice. 
+For example you can generate it in R from a data frame using jsonlite:
+
+```r
+df <- data.frame(
+    package = c("curl", "pdftools", "stringdist"),
+    url = c("https://github.com/jeroen/curl", "https://github.com/ropensci/pdftools", 
+        "https://github.com/markvanderloo/stringdist"),
+    subdir = c(NA, NA, "pkg")
+)
+jsonlite::write_json(df, 'packages.json', pretty = TRUE)
+```
+
+The `url` value __must be a public git url__. 
+This is important; our build servers literally call `git clone ${url}` on each of the entries. 
+The `package` field must match the name of the R package from the DESCRIPTION file under that url.
+If the R package does not live in the root of the git repository, you also need to set the `subdir` field to the path of the R package root directory.
+
+When creating a new universe, start by adding no more than a few packages. 
+You can easily add more packages later by updating your `packages.json` file.
+
+To publish your registry, create a git repository called `<yourname>.r-universe.dev` on your GitHub account and push your `packages.json` file. See for example: https://github.com/maelle/maelle.r-universe.dev.
+
+### Installing the GitHub app
+
+Once you pushed your `packages.json` file to your new `universe` repository on GitHub, the next step is to install the [R-universe GitHub app](https://github.com/apps/r-universe/installations/new) on your account.
+
+[![ghapp](https://jeroen.github.io/runiverse2021/images/installapp.png)](https://jeroen.github.io/runiverse2021/#50)
+
+### Waiting for the first build
+
+Once you installed the app, the system will automatically create your personal monorepo under the r-universe organization: `https://github.com/r-universe/<yourname>`. 
+This is where the system keeps the full history of your packages.
+The actions tap of your monorepo is also where the building happens.
+
+[![builds](https://jeroen.github.io/runiverse2021/images/actions.png)](https://github.com/r-universe/maelle/actions)
+
+After a while (usually no more than one hour), packages and articles that have completed building on all platforms will start appearing on your dashboard, and directly become available for installation by users.
+
+
+[![dashboard](https://jeroen.github.io/runiverse2021/images/maelledash.png)](https://maelle.r-universe.dev)
+
+The GitHub app requires very limited permissions, it only requests permission to *read and write commit statuses*. This means that the R-universe build system can post a green checkmark on your package git commits, once your package is successfully built and deployed to R-universe. Thereby R-universe serves as a full CI-CD system that shows you if your package build and deploy was successful.
+
+[![success](https://jeroen.github.io/runiverse2021/images/commitstatus.png)](https://jeroen.github.io/runiverse2021/#54)
+
+### Adding badges and user instructions
+
+Once your packages have appeared on the dashboard, try installing them in R using the instructions from the dashboard page, for example:
+
+```r
+# Enable this universe
+options(repos = c(
+    maelle = 'https://maelle.r-universe.dev',
+    CRAN = 'https://cloud.r-project.org'))
+
+# Install some packages
+install.packages('tinkr')
+```
+
+To help your users, you can consider copying these instructions to your package README.md files. 
+And of course you can add an r-universe badge to your readme as well.
+
+The badge API is simply `/badges/<package>` which will yield an SVG image that can directly be embedded into your markdown files, showing the deployed version for the given package:
+
+
+```md
+![r-universe](https://r-lib.r-universe.dev/badges/cpp11)
+```
+
+For example this would produce the following badge: <img style="margin-bottom:3px;" src="https://r-lib.r-universe.dev/badges/cpp11"></img>