Getting Started¶

For a video demonstration of a first time setup, including installing a 3rd party module (like astrotoyz) see the video below.

First Time Setup¶

Once you have installed toyz (see Install for instructions on installation) you are ready to setup your local toyz application.

First you need to create a directory that will house the configuration settings, for example ~/toyz. Once you’ve created this directory navigate to it and type

toyz

and you will be promped to setup toyz for the fist time.

Note

You can have more than one instance of a toyz application installed on the same system, and even multiple instances running at the same time on different ports.

Once the first time setup has been completed the application will notify you:

Server is running on port XXXX

where XXXX is the port that toyz is using.

To exit the toyz application at any time just type CTRL + c.

Running a Toyz Application¶

There are a number of different ways to initialize a Toyz web application, and even more ways to connect to a running application. At this time it is recommended that you run Toyz behind a firewall because we haven’t sufficiently vetted the security of the application. Below are some of the possible ways to initialize and connect to a toyz application (btw, if you are a security expert and would like to help make Toyz more secure please stop by the Toyz Google group).

Warning

Unless you are running toyz from the default path, you must always run toyz from the folder you specified during the first time setup, otherwise toyz won’t be able to find your saved settings and will once again prompt you for a first time setup.

Remote server behind a firewall¶

This is the recommended method to run a Toyz Application. In this case you can use port forwarding to connect to the remote server, for example, from your local terminal:

ssh -L<local_port>:localhost:<remote_port> <username>@<hostname>

where local_port is the port on the local machine, remote port is the port on the remote machine, username is your username on the server and hostname is the server you are connecting to. For example:

ssh -L8888:localhost:8888 johndoe@myserver.com

Now navigate to the path where you installed your toyz instance in First Time Setup and type:

toyz --port=<remote_port>

where remote_port is the port you specified above. Now open up the browser of your choice and enter:

localhost:8888

or replace 8888 with the port your application is currently running on. This should bring you to a login screen.

Connecting to a Toyz Server Running on a local (or remote) network¶

If a toyz instance is running on a networked computer, registered users can log on to the application by entering in their browser:

hostname:port

where hostname is the name of the server hosting the application and port is the port specified when the application was lauched. For example enter:

physics_server.pas.rochester.edu:8888

in the browser address bar.

Local Machine¶

If you are just running toyz on your local machine run:

toyz --port=8888

where you can replace 8888 with the port you would prefer to use.

Note

The default port is 8888 so it is possible to simply run toyz from the terminal

Now open up the browser of your choice and enter:

localhost:8888

or replace 8888 with the port your application is currently running on. This should bring you to a login screen.

Configuring a New Toyz Web Application¶

The first time you log on to Toyz the only account will be the admin account, with the default password ‘admin‘. By default security is turned on so you will be prompted to enter ‘admin‘ for both the name and password.

If you are the only user (for example this is installed on your local machine) you are probably ready to run_first_toy . Otherwise you will likely need to follow the next few steps (a more thorough coverage of Toyz settings is given in toyz_settings).

Change Password¶

When a new user is created, the default password is always their username, so all users (including and ESPECIALLY the admin) are highly recommended to change it to something more secure. To do this just click on the change password button in the Account Settings tab. Enter the current password and the new password twice.

Add New Users and Groups¶

Click on the User Settings tab. Scroll down (if necessary) and click on the new user button, then enter the name of a new user. Similarly you go to the Group Settings tab and do the same for new groups.

Modify Permissions for Users and Groups¶

By default all users are given permission to run scripts on the toyz.web.tasks module and have access to their own personal directory created on the server. Members of the admin group (including the admin account) automatically have permissions for all of the files and directories that the user running the web application has access to.

If you have just created new accounts, refresh the page and choose a new user from the dropdown box to add them to any groups or to give them permission to any additional directories or python modules, or toyz installed on the server. For example, there may be a shared images directory that all students in a class are sharing, or a data analysis toy shared by a research group.

Configuraton Settings¶

There are additional settings that are currently hard coded in the application and cannot be changed, only viewed, in the config settings menu. All other settings cannot be displayed at this time.