Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
tree: 0bb5c2a61d
Fetching contributors…

Cannot retrieve contributors at this time

383 lines (273 sloc) 12.223 kb

Advanced Installation


We depend on the following packages:

and optionally:

  • MongoDB
  • PyMongo (at least version 1.10.1, which is newer than the version packaged in some Ubuntu releases)
  • nginx
  • uWSGI

These instructions assume Sage 5.0.beta4 is installed.

In the following instructions, :envvar:`$SERVER` refers to the directory containing all of the software (for example, it might be :file:`/var/sagecellsystem`).

Build dependencies

The builds below have their own dependences, which you will have to install before successfully configuring them. On Ubuntu, this command should take care of most or all of them:

sudo apt-get install uuid-dev zlib1g-dev openssh-server


Install Sage 5.0.beta4. :envvar:`$SAGE_ROOT` refers to the installation directory.

Install the Flask Sage notebook by following the directions at


Download ØMQ and build it in :file:`{$SERVER}/zeromq/installed/`:

tar -xzvf zeromq-2.1.11.tar.gz
ln -s zeromq-2.1.11 zeromq
cd zeromq
./configure --prefix=`pwd`/installed && make install

Python packages

Install the required Python packages.

sudo sage -sh # install into Sage's python
easy_install pip # install a better installer than easy_install
pip install flask
pip install pymongo # only necessary if you will be using MongoDB
pip install pyzmq --install-option="--zmq=$SERVER/zeromq/installed"

Sage Cell Server

The repository for this software is in the sagemath/sagecell repository on GitHub.

Either download the tarball and extract the contents of the contained folder into :file:`{$SERVER}/sagecell`, or use Git to clone the code:

git clone git:// sagecell


Several patches enable Sage to take advantage of the enhanced protocol for communicating graphical displays. In order to patch Sage, apply the patches to your Sage installation found in the :file:`{$SERVER}/sagecell/sage-patches` directory. Apply them in numeric order. We suggest using Mercurial Queues so that it is easy to back out the patches if needed. After applying the patches, rebuild Sage with sage -b.

sage -sh
cd $SAGE_ROOT/devel/sage/
hg qimport $SERVER/sagecell/sage-patches/01-sage-embedded.patch
hg qpush
hg qimport $SERVER/sagecell/sage-patches/02-sage-show.patch
hg qpush
sage -b


In Sage mode, Sage can output 3D graphs in Jmol format. The Jmol Java applet must be installed in order to see these. It is sufficient to make a symbolic link from the :file:`/static` directory over to the appropriate Jmol directory in the Sage notebook:

cd $SERVER/sagecell/static
ln -s $SAGE_ROOT/local/share/jmol .

Configuration and Running

First, minify CSS and JavaScript files, as well as update the various web components we depend on (this is required):

cd $SERVER/sagecell

The only thing left now is to configure and start the Sage cell server. The server will automatically launch a number of workers via passwordless SSH into an untrusted account (i.e., an account with heavy restrictions; this account will be executing arbitrary user code).


The untrusted account will execute arbitrary user code, which may include malicious code. Make sure that you are securing the account properly. Working with a professional IT person is a very good idea here. Since the untrusted accounts can be on any computer, one way to isolate these accounts is to host them in a virtual machine that can be reset if the machine is compromised.

These instructions assume that the locked-down account is on the same computer as the server.

  1. Install OpenSSH if it is not already installed.

  2. Create a new restricted user account and enable passwordless SSH from your account to the restricted account:

    sudo adduser <UNTRUSTED_USER>
    ssh-keygen # not needed if you already have a public key
    sudo mkdir <UNTRUSTED_USER_HOME_DIR>/.ssh
    sudo cp ~/.ssh/ <UNTRUSTED_USER_HOME_DIR>/.ssh/authorized_keys

    Test the passwordless SSH by logging in (:samp:`ssh {<UNTRUSTED_USER>}@localhost`) and out (exit). If you have a passphrase for your key, you may need to type it once, but there should be a way to store the key and log in fully automatically.

  3. Create a configuration file :file:`{$SERVER}/sagecell/` by copying and modifying :file:`{$SERVER}/sagecell/` and make the following changes:

  4. Start the webserver:

    sage -sh
    cd $SERVER/sagecell
  5. Start the trusted server:

    sage -sh
    cd $SERVER/sagecell

    When you want to shut down the server, just press :kbd:`Ctrl-C`. This should automatically clean up the worker processes.

  6. Go to http://localhost:8080 to use the Sage Cell server.

Optional Installation


Follow these steps if you want to use MongoDB as the database for the server. Otherwise, the Sage Cell will use a SQLite database through SQLAlchemy.

  1. Download the appropriate version of MongoDB from here and extract the contents to the :envvar:`$SERVER` directory. Then make a symbolic link named :file:`mongodb-bin` to the installation directory:

    ln -s $SERVER/mongodb-linux-x86_64-2.0.2 $SERVER/mongodb-bin
  2. Make new directories :file:`{$SERVER}/mongodb` and :file:`{$SERVER}/mongodb/mongo`:

    mkdir -p $SERVER/mongodb/mongo
  3. Make a :file:`{$SERVER}/mongodb/mongodb.conf` file. Copy the text below into this file, replacing :samp:`{<MONGODB_PORT>}` with the port you want for your database and :samp:`{<$SERVER>}` with the path of the server directory.

    dbpath = <$SERVER>/mongodb/mongo/
    bind_ip = localhost
    port = <MONGODB_PORT>
    auth = true
    logpath = <$SERVER>/mongodb/mongodb.log
    logappend = true
    nohttpinterface = true
    # Comment the below out (don't just switch to false)
    # in order to cut down on logging
    verbose = true
    cpu = true
  4. Start up the MongoDB daemon (replace the location of mongodb as appropriate):

    cd $SERVER/mongodb/
    $SERVER/mongodb-bin/bin/mongod -f mongodb.conf
  5. OPTIONAL: Now you need to set up usernames and passwords for database access, if the database is running on a shared server.


    MongoDB authentication documentation recommends that you run without authentication, but secure the environment so that the environment is trusted.

    Set up an admin user, authenticate, then set up a user for the sagecelldb database. Since we include the :samp:`{<SAGECELL_USER>}` and :samp:`{<SAGECELL_PASSWORD>}` in a URL later, it's helpful if neither of them contain any of %:/@ (any length of password with letters and numbers would be okay). Change :samp:`{<ADMIN_USER>}`, :samp:`{<ADMIN_PASSWORD>}`, :samp:`{<SAGECELL_USER>}`, and :samp:`{<SAGECELL_PASSWORD>}`, and :samp:`{<MONGODB_PORT>}` to appropriate values:

    $ SERVER/mongodb-bin/bin/mongo --port <MONGODB_PORT> # start up mongo client
    > use admin
    > db.addUser("<ADMIN_USER>", "<ADMIN_PASSWORD>")
    > db.auth("<ADMIN_USER>", "<ADMIN_PASSWORD>")
    > use sagecelldb
    > db.addUser("<SAGECELL_USER>", "<SAGECELL_PASSWORD>")
    > quit()

nginx and uWSGI

You can use nginx and uWSGI to get a more capable webserver.


First, install the :command:`libpcre3-dev` library (if on Ubuntu). This makes it so that when nginx is a reverse proxy, it can rewrite the headers so that the absolute URLs work out correctly.

sudo apt-get install libpcre3-dev

Download nginx and build it in :file:`{$SERVER}/nginx/install/`:

tar -xzvf nginx-1.0.12.tar.gz
ln -s nginx-1.0.12 nginx
cd nginx
./configure --prefix=`pwd`/install --without-http_rewrite_module && make install

Make the :file:`{$SERVER}/nginx/install/conf/nginx.conf` file have only one server entry, as shown here (delete all the others). :samp:`{<SERVER_PORT>}` should be whatever port you plan to expose to the public (different from :samp:`{<MONGODB_PORT>}`).

server {
    listen <SERVER_PORT>;
    server_name localhost;
    charset utf-8;
    client_max_body_size 4M; # Maximum file upload size of 4MB
    location / {
        uwsgi_pass unix:/tmp/uwsgi.sock;
        include uwsgi_params;

Start nginx:



These instructions are based on these instructions. We don't want to require libxml2 (it appears to be only for the config files), so we'll make our own build configuration that doesn't support XML build files.

  1. Get uWSGI:

    cd $SERVER
    tar -xzvf uwsgi-latest.tar.gz
    ln -s uwsgi-1* uwsgi
  2. Change the configuration file to set xml = false:

    cd uwsgi/buildconf
    cp default.ini sagecell.ini
    # edit myproject.ini to make the xml line read: xml = false
    cd ..
  3. Build uWSGI:

    sage -python --build sagecell
  4. Create a symbolic link to uWSGI in :file:`{$SERVER}/sagecell/`:

    ln -s $SERVER/uwsgi/uwsgi $SERVER/sagecell/uwsgi
  5. Set the webserver variable in the file to be 'uwsgi'.


If there are errors when you start the uwsgi server, you may need to change permissions of :file:`/tmp/uwsgi.sock`:

chmod 777 /tmp/uwsgi.sock

Making an spkg

In order to make an spkg, after the cell server is installed, just go into the main cell server repository directory and do:

sage sage-spkg/spkg-dist

The spkg will be made in the :file:`dist/` directory

Jump to Line
Something went wrong with that request. Please try again.