Skip to content

AllAboutProjects

Jump to bottom
Harald Schilly edited this page Jul 28, 2016 · 27 revisions

All about Projects!

Remember: if you don't find what you need, or if you'd like to ask a question, then please email help@sagemath.com at any time. We'd love to hear from you! Please include a link (the URL address in your browser) to any relevant project or document, as part of your email.

List of Questions:

Question: What is a project?

Projects are the fundamental way in which your files on SageMathCloud will be organized. A project is your own private computational work space that you can share with others and upgrade.

For example, all of your files will live in a project (though it is easy to copy files between projects).

Each project has a set of collaborators, who have the ability to read, write, delete, or modify anything in the project (except backups). (See also, What is a collaborator and what can they do?.)

Sometimes, you might rather give someone read-only access. In SageMathCloud, this is called "sharing" with non-collaborators. Click here for details on how to share a file.

Your resource limits (RAM, Disk Storage, CPUs, and the "idle timeout") will be set project-by-project, and can be elevated with upgrades by any collaborator. (See Why upgrade a project? for details.)

Because projects can have folders in them (including folders-within-folders, folders-within-folders-within-folders, and so forth), the files in your project can be as organized or disorganized as you might like.

Technical note: the folders are actually directories in the UNIX/Linux world.

Question: How do I add a new project?

When logged into SageMathCloud, look in the far upper-left corner, and click on "Projects." Then click on the green button "+ Create new project."

You'll be invited to set a project title and a project description, but don't worry too much about the wording. You can very easily change the title and description at any time later. (See also, How do I change the Title and/or Description of a Project?.)

A project can be with or without upgrades. The upgrades are only available to paid subscribers. Free users must click "Create Project without Upgrades."

In the next question, we'll discuss why you might want to upgrade a project.

Question: Why upgrade a project?

There are many reasons that you might want to have an upgraded project, and paid subscriptions start at $ 7 per month.

  • To give your project access to the internet. For example,
    • To download a software package from the internet.
    • To use Github/Bitbucket/Gitlab with your project.
    • To download datasets into your project.
    • To connect to your project with SSH.
  • To get extra storage space (both RAM and disk space).
  • To get more compute resources.
  • To have a higher "idle timeout" threshold. (See also, What is an "idle timeout?".)

You can share upgrades with any project that you are a collaborator on. You must be a collaborator (or owner) to update a project.

For details on paid subscriptions, see Subscription and Pricing Information.

You will not be charged until you select a specific subscription then click "Add Subscription".

If you have any questions at all, email help@sagemath.com immediately.

Question: What is a collaborator and what can they do?

Collaborators can read, write, delete, and modify anything in the project, except backups. They can add and remove other collaborators, but cannot remove owners.

Sometimes, you'd rather give someone read-only access. In SageMathCloud, this is called "sharing" with non-collaborators. Click here for details on how to share a file.

Question: How do I add collaborators?

  1. With the project open, you can see a wrench icon, toward the upper-left corner of the screen. Click that.
  2. In the upper-right part of the settings screen, under "Collaborators," you will see a box labeled: "Add Collaborators."
  3. You can type in a person's name, or their email address. Then SageMathCloud will search its database of known users and give you possible matches.
  4. After you select a name, don't forget to click "Invite User."
  5. The user has to accept the invitation.

Pragmatically, it is better to use an email address. The reason is that some SageMathCloud users have multiple accounts. Also, if someone has a several month haitus from SageMathCloud, they might forget which email address they had used when they created their SageMathCloud account. This is often a point of confusion.

If there are no matches for an email address, then you can send an invitation for the user to start using SageMathCloud. You can modify the standard email. It has useful links to make it easier for the other person to start using SageMathCloud.

Question: How do I change the Title and/or Description of a Project?

  1. With the project open, you can see a wrench icon, toward the upper-left corner of the screen. Click that.
  2. In the upper-left part of the settings screen you will see boxes for the project title and the project description.
  3. When you make a change, a green button marked "Save" will appear. Be certain to click it, otherwise your changes will not take effect.

Question: How can I copy a file from one project to another?

  1. In the upper-left corner of the screen, you'll see a folder icon. Click that.
  2. Click the check-box next to the file or files that you wish to copy.
  3. The "destination" pull-down menu is restricted to the current project... however...
  4. To the left, and slightly upward, you will see "Copy to a folder or a different project." Click on "a different project."
  5. Now you have two pulldown menus, one for the project, and one for the destination within the project.
  6. The button to make this actually happen is on the left, slightly downward, and says "Copy 1 item" or "Copy 3 items", etc...

Question: How can I move a file from one project to another?

This is currently done with the "copy" command, not the "move" command. That's for the safety of your files. If you like, you can copy the file from one project to another, and then delete the original.

Question: How do I switch between projects?

Look in the far upper-left corner, and click on "Projects." Then you will see a list of all of your projects (those that you own and those that you are a collaborator on).

They are sorted by time. In other words, how long it has been since any collaborator made any change in the project. However, there are other ways to organize your projects, using hashtags.

Question: How can I create public projects on SageMathCloud?

You can make individual files and folders public. Pull up information for a file (click the info icon), and click on "Share Publicly". Once you do this, simply share the URL that is displayed in the top of your browser when you look at the file (or directory). Anybody else who views that link will see the file, and can create an account and copy it to their own project.

You can also publish Jupyter notebooks via a Publish button -- see this video.

Question: If I "share" a file, does it become public to everyone and/or searchable? Or is the only way to get to it via a link and a SageMath account?

When you click "Share Publicly" in the info dialog for a file or directory, then yes, it does become public to everyone (as the name "publicly" suggests).

It is NOT searchable (via Google, say) right now, but may become searchable later, when we implement something to encourage that. The only way to get it today is via a link, after you share it publicly. But that is temporary.

The person getting the link does not need a SageMath account -- try opening the link in private browsing mode to see.

Question: If I remove myself as a collaborator on a project that I've upgraded, what happens to the upgrade?

The upgrade is also removed.

Question: How Do I Restart a project?

First, when the project is open, you should see an icon with a wrench marked "settings." This is near the top of the window, towards the left about 1/4th of the way across your screen. Click on that wrench.

Second, there is a box with several items in it, called "Project Control." There is an icon with some gears next to that. Often you have to scroll-down to find that box.

Third, inside that box, there is a button marked "Restart Project..." with a lightening bolt. Click that. By the way, the reason a lightening bolt was used is that this is not a minor operation.

  • All computations will be stopped (in UNIX-language, that means "all processes will be killed").
  • Good News: You don't lose unsaved files.
  • You do lose any information (state of variables/processes) in RAM.
  • However, anything in files, as long as it's moved from the browser to the web servers (in most cases, at most a few seconds of information), is actually permanently saved to disk already in the database, and will not be lost.
  • When the project starts back up, even if the files on disk are in an older state, the files you see yourself editing in your browser are new with nothing lost. Those files will then be updated on disc very shortly.
  • On the other hand, it will update the project code, and start the project running again.

Fourth, after you click on the "Restart Project..." icon, a warning pops up. Read the warning, and then click on "Restart Project Server" if you want to restart the project. Otherwise, hit "cancel."

Fifth, give the project a good 30 seconds to restart. A lot has to happen, and it might take some time.

Question: I can access some of my files/projects in my SageMathCloud account but not others in that same account. What's wrong?

Sometimes this can happen if you are using multiple SageMathCloud accounts in the same browser. This can happen even if you are not using two different accounts simultaneously.

We have a short help page, Tips for using more than one SageMathCloud account which discusses this. The suggestions there will make it work very smoothly for you.

Question: What can I store in a project?

The available webspace is a courtesy to be able to run your computational projects online. It's not for downloading arbitrary stuff from the internet. For more details about our policies, please read https://cloud.sagemath.com/policies/terms.html

Question: What is the difference between Hiding and Deleting a project?

If you delete a project, then you delete it for everyone---for all your collaborators. The good news is that this can be undone.

Alternatively, if you hide a project, then you will not see it in your projects listing, but your collaborators are unaffected.

Question: How do I Hide or Delete a Project?

Note, the previous question describes the difference between hiding a project and deleting a project.

When the project is open, you can see a wrench icon toward the upper-left corner of the screen. Click that and scroll all the way down. In the lower-left part of the settings screen, you will see "Hide or Delete project", with a button for hiding the project and a button for deleting the project.

Actually, if you have one or more hidden projects, then in your projects listing (found by clicking on projects in the far upper-left corner of the screen), there will be a check-box marked "Hidden." Clicking that check-box will show the hidden projects (and no other projects). Similarly, if you have one or more deleted projects, then in your projects listing, there will be a check-box marked "Deleted."

Question: How do I unhide a hidden project?

  1. Click on projects, in the far upper-left hand corner of the screen.
  2. If you have one or more hidden projects, there will be a check-box labeled "hidden" near the center of the top of the screen. Click that.
  3. Now you should see all of your hidden projects. Click on the project that you want to unhide.
  4. Click on the wrench icon to get the settings menu.
  5. Scroll all the way to the bottom. In the lower-left corner, you will see an area called "Hide or Delete project."
  6. There is a button marked "unhide project." Click that button.

Note: A project can be both hidden and deleted. In that case, during Step 2 above, be sure both the "hidden" and "deleted" check boxes are both checked.

Question: How do I undelete a deleted project?

  1. Click on projects, in the far upper-left hand corner of the screen.
  2. If you have one or more deleted projects, there will be a check-box labeled "deleted" near the center of the top of the screen. Click that.
  3. Now you should see all of your deleted projects. Click on the project that you want to undelete.
  4. Click on the wrench icon to get the settings menu.
  5. Scroll all the way to the bottom. In the lower-left corner, you will see an area called "Hide or Delete project."
  6. There is a button marked "undelete project." Click that button.

Note: A project can be both hidden and deleted. In that case, during Step 2 above, be sure both the "hidden" and "deleted" check boxes are both checked.

Question: How do I connect via SSH into one of my SageMathCloud projects?

This is about the Secure SHell (SSH), a tool for connecting securely between two computers. If you're unfamiliar with SSH, then you probably don't want to attempt this.

To SSH into your SageMathCloud project you need to create public/private keys. That's covered by the next question, immediately below. You only have to do this once per project.

After that's done, under "Project Control" in project settings (the wrench icon), you'll find a button labeled "SSH into your project." Click it, and then you will see the ssh command line that you can type (on any computer anywhere) to ssh to your project.

Question: How do I create public/private keys, so that I can SSH into my project?

For Microsoft Windows users, a free SSH client with key generator is Putty; see instructions for generating key with Putty.

On OS X, open a Terminal, then type cat .ssh/id_rsa.pub to see if you already have a public key. If not type ssh-keygen to create a public key. Then type cat .ssh/id_rsa.pub to see your key; you may then copy and paste it into the file .ssh/authorized_keys inside your SageMathCloud project.

** Next Steps:**

Once you have your public key, convert it into the format below---which must all be on one long line!

Next, you must add an ssh public key to your project. After that's done, under "Project Control" in project settings (the wrench icon), you'll find a button labeled "SSH into your project." Click it, and you will see a link "add a public key to ~/.ssh/authorized_keys" right there. Now click on that, and paste an ssh public key into that file, then save it.

This is what you will paste into the file .ssh/authorized_keys in your project in SageMathCloud.

ssh-rsa
AAAAB3NzaC1yc2EAAAABJQAAAQEAkN6u3LIzcNgvWE3iNm4sySrR8X7UAc0ydWCKDZXaPM8XVhrCX3O5V+wyxufyZPDh3NmarDLoiLKTSVJap5tU05UKbO5lyINz76y+/LX74VOZf1lB+TiTgsXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXVNMFPYTG1mSaSLv8wDzFgF+CDfm9IOWZKZFERlGzUokEflQ89tQMPywKEfo/L1TJo3mJwWG3yg8gFmkKE4pfX1hF2Dyq5hHS/8L5YvCu141wITwkmtv+LYdui8WpWL5p8egBDjjMYRy0ChcNb3hmAo8xIRJ7YzGw+9uxsPUAebsQuUPCbx+19r3UQOJ8mgsP1tyjHLw==

Now you can ssh to your project. Right there, under "Project Control", you will see the ssh command line that you can type (on any computer anywhere) to ssh to your project.

Question: I created an ssh key in my project; how do I easily copy it?

If you type ssh-keygen in a terminal, then you'll generate an ssh key, which you might use with github (say) or sage's trac to easily push and pull to repositories. To copy this ssh key, you could type cat .ssh/id_rsa.pub and copy in the terminal, but you'll have to manually delete a bunch of newlines. Alternatively, do the following:

  1. In the project file list, click on the icon that looks like an eye in the middle on the right side of the screen to reveal hidden files (those that start with a dot).

  2. Click on the .ssh directory -- you can easily find it by typing "ssh" in the search box labeled "choose files..." on the left.

  3. Click on id_rsa.pub, then highlight everything and copy as usual.

  4. Click the eye again to turn off viewing hidden files.

Alternatively, type this into the small "terminal command" box in "files": cat ~/.ssh/*.pub. Below the box, you can conveniently copy/paste it!

You can also type the following into a full terminal: open ~/.ssh/id_rsa.pub

Question: "I would like to use hashtags to describe my projects" or "I want to categorize my projects"

You can put #foo in the title or description of any project. When you view your list of projects a button will appear for each hashtag, which you can click to show only projects with that tag. There is also excellent support for hashtags in task lists (SageMathCloud's todo list functionality).

Question: I want to start long-running numerically intensive computations on SageMathCloud. What are the current limitations?

Open your project and click on Settings. The default limitations are listed under "Quotas" in the lower left. These can be raised, as mentioned there. Notes:

  1. Projects on free non-members only Virtual Machines will get restarted regularly (these are hosted on Google preemtible instances). You can check if a VM rebooted by typing "uptime". crontab files are persistent.

  2. If a project isn't used (via the web-based UI) for the idle timeout (as listed in quotas), then all processes in that project are terminated and the user is removed (so ssh into the project also is not possible). You can pay to raise the idle timeout. See also, What is an "idle timeout?".

Question: I want some scratch space

Use /tmp. Files in /tmp may be deleted at any time, and aren't backed up.

Question: Will my code keep running if I disconnect? Even if my computer is put to sleep? Or do I need to have a machine open in order for the process to run?

You definitely do not need to have your computer awake, or a window open, for your project to keep working. However, this is controlled by something called an "idle timeout," described in the next question.

Question: What is an "idle timeout?"

Under project settings (that's the wrench icon) there is an entry under "Project Usage and Quotas" (left-hand side), which will tell you how long the process will run "in the background." There is an idle timeout for each project, and it will be completely stopped (the technical term in UNIX is "killed") if you don't actively edit a file for that amount of time.

The default for free projects is 1 hour. You can increase this to 24 hours for only $7 per month. This means that if you use your project a little bit once per day, then it will never timeout.

However, free projects have another limitation. A free project can be "killed" (stopped) at any time, whatsoever. This will happen at least once per day. You have to keep this in mind when designing your project. (For example, use checkpointing.) In contrast, all paid projects are immune to this issue. See also Subscription and Pricing Information.

The next question will discuss the output of your processes.

Question: If I have code that has been running for a while, and it times out or is otherwise "killed" (see previous question), what happens to the output?

If you are using a Jupyter notebook, then all output that is printed will be lost if no browser is viewing it. This is a major design flaw in Jupyter.

In contrast, Sage worksheets will capture output even if no browser is observing them.

You can also (of course) write to a file on disk, which might be preferable in some cases.

Question: I want to see all processes running in my project

Type exactly the following in a full terminal (+New--> Terminal) to see all processing running in a project:

htop

You can kill things, etc. See http://linux.die.net/man/1/htop.

Question: I want to know how much memory I am using

Type exactly the following in a full terminal (+New--> Terminal):

smem -tk

It lists all processes and the bottom line shows the total sum. The last RSS column is probably the most interesting one, for more consult man smem. The total used memory is also listed under 'Project usage and quotas" in project settings.

Question: How do I raise the limit on the number of output messages per cell in a Sage worksheet?

import sage_server
sage_server.MAX_OUTPUT_MESSAGES=100000

See this published worksheet for more details.

Also, type sage_server.[tab key] to see information about other limitations.

Question: I want to XXX, but I don't see XXX above.

Do not hesitate to email THE LINK TO YOUR PROJECT TO help@sagemath.com or https://groups.google.com/forum/?fromgroups#!forum/sage-cloud and ask a question.

Analytics

This Wiki is for CoCalc.com.

A more structured documentation is the CoCalc User Manual.

For further questions, please contact us.

Clone this wiki locally