Getting started

This page uses Framework Public Cloud at framework.pub. On your own server, replace framework.pub with your server's address.

1. Account registration

Open framework.pub/register and sign up with GitHub or your email address. There is no password to set. If you sign up by email, you get a link that confirms the address and signs you in.

You can sign up with a personal email address. The address you sign in with stays private. The email shown on your work comes from your profile, which you set in the next step. See Signing in.

2. Author profile

Open Account > Profile and enter your name, the email you want shown on your work, your ORCID iD, your website, and up to five affiliations. Framework writes these into the author block of every new notebook, report, and slide deck.

3. R and Python connections

Connect each computer once. Install the Framework package, then run cloud_login() with no arguments. In Python the package is framework-py (pip install --pre framework-py while it is a pre-release).

framework::cloud_login()

import framework

framework.cloud_login()

cloud_login() shows what connecting shares and asks you to confirm. Then it shows a code and opens the approval page in your browser. Sign in, or create a free account, and approve the computer. The token is stored in your system's credential store, such as the macOS Keychain. R, Python, Stata, and fw all use it. Without a credential store, the token goes in a private file in ~/.config/framework. Later sessions and new projects reuse the connection.

In Stata, run fw_login. In a terminal, run fw login. Both use the same approval page. See Framework for Stata.

On your own server, add the server's address:

framework::cloud_login(url = "https://framework.example.edu")

import framework

framework.cloud_login(url="https://framework.example.edu")

Framework remembers the server, so later commands use it. Run cloud_status() to see which server is in use.

On a computer without a browser, create a token on the API tokens page and pass it instead: cloud_login("<your token>"). The page shows the full command. A token is shown only once.

4. Project setup

Open Projects > New project.

1. Choose a blueprint. Open one to see the folders, packages, and templates it sets up.
2. Name the project.
3. Choose where to set it up:
   • On your computer. You get a project token and the command to run with it. In R it is framework::setup("<project token>"), and in Python it is framework.new(key="<project token>"). Framework builds the project. On a self-hosted server, the page adds url = (R) or url= (Python) with the server's address.
   • On GitHub. Framework Cloud creates the repository and builds the project there. Clone it and start working. See GitHub integration.

You can also start on your machine. After signing in with cloud_login(), new_project() in R or Python uses your Cloud settings and registers the new project in your account. Its project token stays in the local, ignored .env file. The project definition is shared. Your datasets are not uploaded. Use offline = TRUE in R or offline=True in Python to create locally without contacting Cloud.

Git ignore rules

Every Framework project structure has a .gitignore template. It keeps private data, credentials, and local files out of Git. The sensitive-data structure adds rules for private inputs, references, and outputs. Course structures also exclude grades, submissions, and student data.

Open Project structures, choose Copy and edit, and use the .gitignore editor to change the rules. Save the structure and choose that version in your blueprint. New projects receive those rules alongside the package's defaults. Use ! patterns to override a default when needed. Saved projects keep their chosen version until you update them.

Ignore rules do not remove files already tracked by Git. Optional pre-commit checks can catch private data staged for a commit and missing ignore rules. Review both the rules and the files before sharing a repository.

5. Notebook publishing

From inside the project:

framework::publish("notebooks/analysis.qmd")

import framework

framework.publish("notebooks/analysis.qmd")

Framework renders the notebook and uploads it. The result is a link you can send to collaborators. See Publishing artifacts.

Local files and Cloud storage

Framework's packages work without a Cloud account. Framework Cloud works without the packages.

Project files

The files are the same kind in every path: folders, settings.yml, the data catalog, notebook settings, and the .gitignore rules. A colleague who reruns the project needs the project files, the input data, and Framework for R or Python. They don't need a Cloud account.

Cloud data

• Your account, author details, and default settings.
• The blueprints and project structures you save.
• Each project's definition: its blueprint, structure, and choices.
• The artifacts, collections, and reports you publish.
• For a connected project, a ledger of saved datasets: each dataset's name, fingerprint, and size. The data itself is not uploaded.

Local files

• Your input data, unless you publish it. Publishing a data frame uploads its rows as a table.
• The local framework.db record of reads and fingerprints.
• The .env file and its tokens. The project's .gitignore keeps them out of Git.

A standard project's .gitignore doesn't exclude inputs/. Use the sensitive-data structure, or add rules, to keep data out of a repository.

Cloud-dependent actions

• Starting a project from a saved blueprint.
• Publishing to Framework Cloud, and collections and reports.
• The dataset ledger and skill sync.

Reading cataloged data, verifying inputs, and publishing to GitHub Pages work without Cloud.

Edit this page on GitHub