Commit 95088cf1 authored by Robert Ricci's avatar Robert Ricci

Partway through the "Creating Profiles" section

parent 97effa01
......@@ -4,4 +4,123 @@
@title[#:tag "creating-profiles" #:version apt-version]{Creating Profiles}
@TODO{This Section To Be Written!}
Using Apt, you can share your research artifacts with others by creating your
own profiles. When you create a new profile, you are creating a new
@secref["rspec"], and, usually, creating one or more @seclink["image"]{disk
images} that are referenced by that RSpec.
When someone uses your profile, they will get their own @secref["experiment"]
that boots up the resources (virtual or physical) described by the RSpec.
@section{Creating a profile from an existing one}
The easiest way to create a new profile is by cloning an existing one and
customizing it to your needs. The basic steps are:
@itemlist[ #:style 'ordered
@item{Find an existing profile that's closest to your needs}
@item{Create an experiment using that profile}
@item{Log into the node(s) in your experiment to install your software,
configure the operating system, etc.}
@item{``Clone'' the experiment to create a new profile}
]
@subsection{Preparation and precautions}
To create profiles, you need to be a @seclink["register"]{registered user}.
Creating a profile can take a while, so we recommend that you
@seclink["extend"]{extend your experiment} while creating it, and contact us
if you are worried your experiment might expire before you're done creating
your profile. We also strongly recommend testing your profile fully before
terminating the experiment you're creating it from.
If you want your profile to be usable by @seclink["guests"]{guest users}, keep
in mind that there are @seclink["guests"]{several restrictions} placed on them;
among these is the fact that they are not allowed to make outgoing connections,
meaning that the experiment must be self-contained. For example, they will not
be able to download software or datasets from within the experiment---it should
all be contained as part of the profile.
Your home directory is @bold{not} included in the disk image snapshot! You
will need to install your code and data elsewhere in the image. We recommend
@code{/local/}. Keep in mind that others who use your profile are going to have
their own accounts, so make sure that nothing in your image makes assumptions
about the username, home directory, etc. of the user running it.
For the time being, this process only works for single-node profiles; we will
add support for multi-node profiles in the future.
@subsection{Creating the Profile}
@itemlist[ #:style 'ordered
@instructionstep["Create an experiment"]{Create an experiment using the
profile that is most similar to the one you want to build. Usually, this
will be one of our facility-provided profiles with a generic installation
of Linux.}
@instructionstep["Set up the node the way you want it"]{Log into the node
and install your software, datasets, packages, etc. Note the
@seclink["profile-creation-preparation"]{caveat above} that it needs to be
installed somewhere outside of your home directory, and should not be tied
to your user account.}
@instructionstep["Clone the epxeriment to create a new profile"
#:screenshot "clone-button.png" ]{
While you are logged in, the experiment page for your active experiments
will have a ``clone'' button. Clicking this button will create a new
profile based on your running experiment.
Specifically, the button creates a copy of the @secref{"rspec"} used
to create the experiment, passes it to the form used to create new
profiles, and helps you create a @seclink["image"]{disk image} from your
running experiment.
}
@instructionstep["Fill out information for the new profile"
#:screenshot "create-profile-form.png" ]{
After clicking on the ``clone'' button, you will see a form that
allows you to view and edit the basic information associated with your
profile.
Each profile must be associated with a @secref["project"]. If you're
a member of more than one project, you'll need to select which one you
want the profile to belong to.
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
displayed when @seclink["proflinks"]{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
associated with a paper or other publication, this is a good place to
mention that. @seclink["markdown"]{Markdown} markup, including hyperlinks,
are allowed in the profile description.
The ``Instructions'' text is displayed on the experiment page after the
user has created an experiment using the profile. This is a good place
to tell them where the code and data can be found, what scripts they
might want to run, etc. Again, @seclink["markdown"]{Markdown} is allowed.
The ``Steps'' section allows you to create a @secref{"tour"} of your
profile, which is displayed after a user creates an experiment with it.
This feature is mostly useful if your profile contains more than one
node, and you wish to explain to the user what the purpose of each node
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
@seclink["proflinks"]{direct link} that you can use to share your
profile with others of your chosing.
}
]
@subsection{Sharing a Profile}
@subsection{Updating a profile}
@section{Creating a profile from scratch}
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