*************** Getting Started *************** For a video demonstration of a first time setup, including installing a 3rd party module (like astrotoyz) see the video below. .. raw:: html .. _first_time_setup: First Time Setup ================ Once you have installed toyz (see :ref:`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_toyz: 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:localhost: @ 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 :ref:`first_time_setup` and type:: toyz --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 :ref:`run_first_toy` . Otherwise you will likely need to follow the next few steps (a more thorough coverage of Toyz settings is given in :ref:`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.