Commit 643d3374 authored by Robert Ricci's avatar Robert Ricci

Macro-ize the name of the facility

Use @(tb) instead of "Apt", "CloudLab", etc. to make it generic.

I left alone a couple of pages that are going to always be apt-specific
parent eef86d8e
......@@ -20,14 +20,14 @@ as manipulate with other tools or create as a ``compiled'' target from a
higher-level language.
That said, the tools for manipulating RSpecs are still incomplete. (For a
preview of Apt's plans in this regard, see our section on
preview of @(tb)'s plans in this regard, see our section on
@seclink["planned-easier-profiles"]{planned profile creation features}.) So,
there are still some cases in which it is unfortunately useful to look at or
manipulate RSpecs directly.
@(under-construction)
@italic{Still to come: documentation of Apt's extensions to the RSpec format.}
@italic{Still to come: documentation of @(tb)'s extensions to the RSpec format.}
@section[#:tag "public-ip-access"]{Public IP Access}
......@@ -35,7 +35,7 @@ manipulate RSpecs directly.
@section[#:tag "markdown"]{Markdown}
Apt supports
@(tb) supports
@hyperlink["http://daringfireball.net/projects/markdown/"]{Markdown}
in the major text fields in @seclink["rspecs"]{RSpecs}. Markdown is a simple
formatting syntax with a straighforward translation to basic HTML elements
......
This diff is collapsed.
......@@ -4,7 +4,7 @@
@title[#:tag "creating-profiles" #:version apt-version]{Creating Profiles}
Using Apt, you can share your research artifacts with others by creating your
Using @(tb), you can share your research artifacts with others by creating your
own profiles. When you create a new profile, you are creating a new
@seclink["rspecs"]{RSpec}, and, usually, creating one or more
@seclink["disk-images"]{disk images} that are referenced by that RSpec.
......@@ -95,7 +95,7 @@ add support for multi-node profiles in the future.
Make sure to edit the profile's Description and Instructions.
The ``Description'' is the text that users will see when your profile is
listed in Apt, when the user is selecting which profile to use. It is also
listed in @(tb), when the user is selecting which profile to use. It is also
displayed when @seclink["sharing-profiles"]{following a direct link to your
profile}. It should give the reader a brief description of what they will
get if they create an experiment with this profile. If the profile is
......@@ -115,8 +115,8 @@ add support for multi-node profiles in the future.
is.
You have the option of making your profile usable to anyone, only
registered Apt users, or members of your project. Regardless of the
setting you chose here, Apt will also give you a
registered @(tb) users, or members of your project. Regardless of the
setting you chose here, @(tb) will also give you a
@seclink["sharing-profiles"]{direct link} that you can use to share your
profile with others of your choosing.
}
......@@ -177,7 +177,7 @@ is to @seclink["getting-help"]{contact us}.
@future-work["planned-easier-profiles"]
Apt profiles are described by
@(tb) profiles are described by
@hyperlink["http://groups.geni.net/geni/wiki/GENIExperimenter/RSpecs"]{GENI
RSpecs}. You can create a profile directly from an RSpec by using the
``Create Profile'' option from the ``Actions'' menu. Note that you cannot edit
......@@ -189,7 +189,7 @@ fields in the RSpec.
@future-work["planned-versioned-profiles"]
If you chose to make your profile publicly visible, it will show up in the main
``Select Profile'' list on @url[(apturl)]. Apt also gives you direct links to
``Select Profile'' list on @url[(apturl)]. @(tb) also gives you direct links to
your profiles so that you can share them with others, post them on your
website, publish them in papers, etc. The link can be found on the profile's
detail page, which is linked for your ``My Profiles'' page. If you chose to
......
......@@ -10,6 +10,8 @@
(define apt-base-url "https://www.aptlab.net/")
(define tb (lambda () "Apt"))
; We want the 'version' to be the date of the most recent commit
(define apt-version
(with-output-to-string
......
......@@ -4,7 +4,7 @@
@title[#:tag "getting-help" #:version apt-version]{Getting Help}
The help forum is the main place to ask questions about Apt, its use, its
The help forum is the main place to ask questions about @(tb), its use, its
default profiles, etc. Users are strongly encouraged to participate in
answering other users' questions. The help forum is handled through Google
Groups, which, by default, sends all messages to the group to your email
......
......@@ -4,7 +4,7 @@
@title[#:tag "getting-started" #:version apt-version]{Getting Started}
This chapter will walk you through a simple experiment on Apt and
This chapter will walk you through a simple experiment on @(tb) and
introduce you to some of its @seclink["basic-concepts"]{basic concepts}.
Start by pointing your browser at @url[(apturl)].
......@@ -12,17 +12,17 @@ Start by pointing your browser at @url[(apturl)].
@itemlist[#:style 'ordered
@instructionstep["Enter your email address and pick a username"
#:screenshot "instantiate-empty.png"]{
If you don't have an account, or are not logged in, you'll be using Apt
If you don't have an account, or are not logged in, you'll be using @(tb)
as a @seclink["guest-users"]{guest user}. Guest users have some
@seclink["guest-users"]{restrictions} placed on them, but this is a quick way
to get started. Enter your email address and pick a username. This username
will be the one you'll use to log into your nodes (eg. via @(ssh)), and
if you @seclink["register"]{sign up} for an account on Apt later, it will
become your Apt username as well.
if you @seclink["register"]{sign up} for an account on @(tb) later, it will
become your @(tb) username as well.
You may leave the @(ssh) key portion of the form blank---if you do, the only
way to log into your nodes will be through a browser-based terminal that we
provide. We recommend that if you use Apt heavily, you upload a public key,
provide. We recommend that if you use @(tb) heavily, you upload a public key,
which will enable you to use a regular @(ssh) client.
}
......@@ -39,7 +39,7 @@ Start by pointing your browser at @url[(apturl)].
specifies the @seclink["disk-images"]{operating system and installed
software}.
Profiles come from two sources. Some of them are provided by Apt itself, and
Profiles come from two sources. Some of them are provided by @(tb) itself, and
provide standard installation of popular operating systems, software stacks,
etc. Others are @seclink["creating-profiles"]{created by other researchers}
and may contain research software, artifacts and data used to gather published
......@@ -55,16 +55,16 @@ Start by pointing your browser at @url[(apturl)].
}
@instructionstep["Click Create!"
#:screenshot "please-wait.png"]{
When you click the ``Create'' button, Apt will start preparing your experiment
When you click the ``Create'' button, @(tb) will start preparing your experiment
by selecting nodes, installing software, etc. as described in the profile.
What's going on behind the scenes is that on one (or more) of the machines
in one of the @seclink["hardware"]{Apt clusters}, a disk is being imaged,
in one of the @seclink["hardware"]{@(tb) clusters}, a disk is being imaged,
a VM created and booted, accounts created for you, etc. This process usually
takes a couple of minutes.
If you have never used this email address with Apt before (or if you switch
computers or browsers), Apt will send a verification email. Watch your
email and enter the code into Apt when prompted. (If it doesn't arrive in
If you have never used this email address with @(tb) before (or if you switch
computers or browsers), @(tb) will send a verification email. Watch your
email and enter the code into @(tb) when prompted. (If it doesn't arrive in
a few minutes, check your spam folder!)
}
@instructionstep["Use your experiment"
......@@ -96,7 +96,7 @@ Start by pointing your browser at @url[(apturl)].
often. You can use the ``Extend'' button to submit a request to hold it
longer, or the ``Terminate'' button to end it early.
@seclink["registered-users"]{Registered users} get to hold their experiments
for longer, so if you want to use Apt for much serious work, we recommend
for longer, so if you want to use @(tb) for much serious work, we recommend
@seclink["register"]{registering for an account}.
}
]
......@@ -104,13 +104,13 @@ Start by pointing your browser at @url[(apturl)].
@section{Next Steps}
@itemlist[
@item{If you find Apt useful, @seclink["register"]{sign up} for an
@item{If you find @(tb) useful, @seclink["register"]{sign up} for an
@seclink["users"]{account}---having one gives you access to more resources
and lets you run longer experiments.}
@item{Making your own profiles is easy: see the
@seclink["creating-profiles"]{chapter on profile creation} for instructions.}
@item{If you need help, or have questions or comments about Apt's features,
@item{If you need help, or have questions or comments about @(tb)'s features,
@seclink["getting-help"]{contact us}!}
]
......@@ -4,7 +4,7 @@
@title[#:tag "planned" #:version apt-version]{Planned Features}
This chapter describes features that are planned for Apt or under development:
This chapter describes features that are planned for @(tb) or under development:
please @seclink["getting-help"]{contact us} if you have any feedback or
suggestions!
......@@ -23,24 +23,24 @@ where it is appropriate to share with others, it can be published. Users will
be able to link to a specific version---example, to unambiguously identify which
version was used for a paper.
One limitation on this feature will be the fact that Apt has limited storage
One limitation on this feature will be the fact that @(tb) has limited storage
space; we will have to apply a quota system that limits the amount of storage
that a project can use to store multiple versions of the same profile.
@section[#:tag "planned-persistent-storage"]{Persistent Storage}
For the time being, the contents of all disks in Apt are considered ephemeral:
For the time being, the contents of all disks in @(tb) are considered ephemeral:
the contents are lost whenever an experiment terminates. The only way to save
data is to copy it off or to @seclink["creating-profiles"]{create a profile}
using the disk.
We plan to change this by adding persistent storage that is hosted on storage
servers within Apt. Users will be able to use the Apt web interface to create
servers within @(tb). Users will be able to use the @(tb) web interface to create
and manage their persistent storage, and profiles will be able to reference
where these stores should be mounted in the experiment. When sharing profiles,
it will be possible to indicate that the persistent store may only be mounted
read-only---a common use case will be to put a dataset in a persistent store,
and allow other Apt users read-only access to the dataset.
and allow other @(tb) users read-only access to the dataset.
There will be two types of persistent storage: @italic{block stores} which
are mounted using iSCSI, and which generally can only be mounted on one host
......@@ -61,14 +61,14 @@ I/O performance, all data should be copied to local disk before use.
@section[#:tag "planned-easier-profiles"]{Easier From-Scratch Profile Creation}
Currently, there are two ways to create profiles in Apt:
Currently, there are two ways to create profiles in @(tb):
@seclink["creating-from-existing"]{cloning an existing profile} or creating one
from scratch by @seclink["creating-from-scratch"]{writing an RSpec by hand}.
We plan to add two more: a GUI for RSpec creation, and bindings to a programming
language for generation of RSpecs.
The GUI will be based on Jacks, an embeddable RSpec editor currently in
development for the GENI project. Jacks is already used in Apt to display
development for the GENI project. Jacks is already used in @(tb) to display
topologies in the profile selection dialog and on the experiment page.
The programming language bindings will allow users to write programs in an
......@@ -91,6 +91,6 @@ As recommended in the chapter about @seclink["repeatable-research"]{repeatable
research}, moving back and forth between @seclink["virtual-machines"]{virtual}
and @seclink["physical-machines"]{physical} resources is a good way to move
from doing preliminary work to gathering final results for publication. Doing
this currently requires making two profiles. We plan to make changes to the Apt
this currently requires making two profiles. We plan to make changes to the @(tb)
interface to allow users to select, at experiment creation time, whether to use
virtual or physical resources.
......@@ -3,11 +3,11 @@
@title[#:tag "repeatable-research" #:version apt-version]{Apt and Repeatable Research}
One of Apt's key goals is to enable @italic{repeatable research}---we aim to
One of @(tb)'s key goals is to enable @italic{repeatable research}---we aim to
make it easier for researchers to get the same software and hardware
environment so that they can repeat or build upon each others' work.
@seclink["virtual-machines"]{Virtual machines} in Apt do @bold{not} provide
@seclink["virtual-machines"]{Virtual machines} in @(tb) do @bold{not} provide
strong resource guarantees or performance isolation from other concurrent
users. Therefore, they are suitable primarily under the following conditions:
......@@ -28,7 +28,7 @@ environment do the following:
physical machine is often an inefficient use of resources.}
@item{Switch to @seclink["physical-machines"]{physical machines} to collect
numbers of publication. This ensures that published numbers are not
affected by interference from other users of Apt.}
affected by interference from other users of @(tb).}
]
Similarly, for those who are repeating or building on the work of others, we
......@@ -45,6 +45,6 @@ recommend:
@future-work["planned-virt-switching"]
Because the @seclink["disk-images"]{disk images} that Apt provides boot on both
Because the @seclink["disk-images"]{disk images} that @(tb) provides boot on both
virtual and physical machines, in most cases, switching means simply modifying
one's profile to request the other type of resource.
#lang scribble/manual
@(require "defs.rkt")
@title[#:tag "users" #:version apt-version]{Apt Users}
@title[#:tag "users" #:version apt-version]{@(tb) Users}
You may either use Apt as a @seclink["guest-users"]{guest} or as a
You may either use @(tb) as a @seclink["guest-users"]{guest} or as a
@seclink["registered-users"]{registered user}.
Using Apt as a guest is a great way to give it a try; if you find it useful
Using @(tb) as a guest is a great way to give it a try; if you find it useful
and want to start using it for ``real work,'' you should
@seclink["register"]{sign up for a (free) account}, because a guest account (1)
won't let you hold your experiments for very long and (2) only allows you to
......@@ -16,12 +16,12 @@ strong performance isolation from other users.
@section[#:tag "guest-users"]{Guest Users}
You may become a guest user simply by entering your email address on Apt's
You may become a guest user simply by entering your email address on @(tb)'s
@hyperlink[(apturl "instantiate.php")]{``Instantiate an Experiment''} page and
picking a username. Apt will send you an email with a verification code - be
picking a username. @(tb) will send you an email with a verification code - be
sure to check your spam folder if you don't receive it within a few minutes.
You'll remain logged in to Apt as long as you use the same browser and it
You'll remain logged in to @(tb) as long as you use the same browser and it
retains its cookies. If you get logged out for any reason, simply enter the
same email address and username again, and you'll be sent a new verification
code.
......@@ -40,33 +40,33 @@ Guest users are limited in several ways:
@item{Guest users may not create profiles}
]
If you are going to use Apt for much serious work, we encourage you to
If you are going to use @(tb) for much serious work, we encourage you to
@seclink["register"]{register for an account}.
@section[#:tag "registered-users"]{Registered Users}
Registering for an account is @seclink["register"]{quick and easy}. Registering
doesn't cost anything, it's simply for accountability. We just ask that if
you're going to use Apt for anything other than light use, you tell us a bit
more about who you are and what you want to use Apt for.
you're going to use @(tb) for anything other than light use, you tell us a bit
more about who you are and what you want to use @(tb) for.
Users in Apt are grouped into @seclink["projects"]{@italic{projects}}: a
Users in @(tb) are grouped into @seclink["projects"]{@italic{projects}}: a
project is a (loosely-defined) group of people working together on some common
goal, whether that be a research project, a class, etc. Apt places a lot of
goal, whether that be a research project, a class, etc. @(tb) places a lot of
trust on project leaders, including the ability to authorize others to use the
Apt. We therefore require that project leaders be faculty, senior research
@(tb). We therefore require that project leaders be faculty, senior research
staff, or others who are relatively senior positions.
@section[#:tag "register"]{Register for an Account}
To get an account on Apt, you either @seclink["join-project"]{join an existing
To get an account on @(tb), you either @seclink["join-project"]{join an existing
project} or @seclink["create-project"]{create a new one}. In general, if you are
a student, you should join a project led by a faculty member with whom
you're working.
If you already have an account on
@hyperlink["http://www.emulab.net/"]{Emulab.net}, you don't need to sign
up for a new account on Apt---simply log in with your Emulab username and
up for a new account on @(tb)---simply log in with your Emulab username and
password.
@subsection[#:tag "join-project"]{Join an existing project}
......@@ -74,7 +74,7 @@ password.
@screenshot["join-project.png"]
To join an existing project, simply use the ``Sign Up'' button found on every
Apt page. The form will ask you a few basic questions about yourself and the
@(tb) page. The form will ask you a few basic questions about yourself and the
institution you're affiliated with.
An SSH public key is required; if you're
......@@ -82,14 +82,14 @@ unfamiliar with creating and using ssh keypairs, we recommend taking a look
at the first few steps in
@hyperlink["https://help.github.com/articles/generating-ssh-keys"]{GitHub's
guide to generating SSH keys}. (Obviously, the steps about how to upload the
keypair into GitHub don't apply to Apt.)
keypair into GitHub don't apply to @(tb).)
@margin-note{Apt will send you email to confirm your address---watch for it (it
@margin-note{@(tb) will send you email to confirm your address---watch for it (it
might end up in your spam folder), as your request won't be processed until
you've confirmed your address.}
You'll be asked to enter the project ID for the project you are asking to
join; you should get this from the leader of the project, likely your advisor
or your class instructor. (If they don't already have a project on Apt, you
or your class instructor. (If they don't already have a project on @(tb), you
can @seclink["create-project"]{ask them to create one}.) The leader of your
project is responsible for approving your account.
......@@ -102,9 +102,9 @@ project is responsible for approving your account.
senior research staff, or in some other senior position. Students should ask
their advisor or course instructor to create a new project.}
To start a new project, use the ``Sign Up'' button found on every Apt page. In
To start a new project, use the ``Sign Up'' button found on every @(tb) page. In
addition to basic information about yourself, the form will ask you a few
questions about how you intend to use Apt. The application will be reviewed
questions about how you intend to use @(tb). The application will be reviewed
by our staff, so please provide enough information for us to understand the
research or educational value of your project. The review process may take
a few days, and you will receive mail informing you of the outcome.
......@@ -118,7 +118,7 @@ still require that the project leader be the faculty member, as we require that
there is someone in a position of authority we can contact if there are
questions about the activities of the project.
Note that projects in Apt are publicly-listed: a page that allows users to
Note that projects in @(tb) are publicly-listed: a page that allows users to
see a list of all projects and search through them does not exist yet, but
it will in the future.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment