Skip to content
Permalink
Browse files

Updated installation instructions (#1683)

* Updated installation instructions

* Made changes to the installation instructions

* Added more info for Manual Installation

Also made the installation instructions are bit better to read :)

* Fixed broken links

* Fixed a few typos
  • Loading branch information...
sdalmeida authored and gideonthomas committed Feb 3, 2017
1 parent 38980e9 commit dde580e4f6b29534d3118b52106a7578c72f2929
Showing with 116 additions and 24 deletions.
  1. +116 −24 README.md
140 README.md
@@ -19,53 +19,145 @@ how it works in [this blog post](http://blog.humphd.org/thimble-and-bramble/).

Thimble requires a modern web browser, and we recommend using Mozilla Firefox or Google Chrome.

Setup
-----
#Setup/Installation

### Requirements
Thimble interacts with the Publish API (source managed in [publish.webmaker.org](https://github.com/mozilla/publish.webmaker.org)) to store users, projects, files and other content as well as publish user projects.

- Node.js (version 4.6 or later) [[download](https://nodejs.org/en/download/)]
- Virtualbox (version 5.1 or later) [[download](https://www.virtualbox.org/wiki/Downloads)]
- Vagrant (version 1.9 or later) [[download](https://www.vagrantup.com/downloads.html)]
- __Note:__ On Windows machines, you may need to restart your computer after installing Vagrant for it to be fully usable
For authentication and user management, Thimble uses Webmaker OAuth which consists of the Webmaker ID System (source managed in [id.webmaker.org](htps://github.com/mozilla/id.webmaker.org)) and the Webmaker Login API (source managed in [login.webmaker.org](https://github.com/mozilla/login.webmaker.org)).

The setup of Thimble can be divided into two distinct sections:
All three services along with Thimble are bundled together using Git subtrees and can either be run together using Vagrant, or [manually](#manual-installation).

### Editor
## Automated Installation (Preferred Method)
**Note:** If you aren't able to properly run virtualization software on your machine (for e.g. some versions of Windows only allow one virtualization client to run at a time and if that isn't VirtualBox, you can't run the required VirtualBox as well. This is often a problem if you have docker installed on Windows) or are trying to host Thimble on your own, refer to the [Manual Installation](#manual-installation) instructions instead.

To fully use Thimble locally, you need to first setup Brackets locally first. This can be done by following the steps outlined below:
### Prerequisites for Automated Installation
In order for Thimble to be installed correctly, the following dependencies need to be installed in order:

- Node.js (version 4.6 or later) [[download](https://nodejs.org/en/download/)]
- [Brackets (Bramble)](#installing-brackets-bramble)
- Virtualbox (version 5.1 or later) [[download](https://www.virtualbox.org/wiki/Downloads)]
- Vagrant (version 1.9 or later) [[download](https://www.vagrantup.com/downloads.html)]
- __Note:__ On Windows machines, you may need to restart your computer after installing Vagrant for it to be fully usable.

### Installing Brackets (Bramble)
- Fork the [Brackets repository](https://github.com/mozilla/brackets) and then clone it to your local machine using `git clone --recursive https://github.com/<your_username>/brackets.git` (replace `<your_username>` with your Github username for the account you forked Brackets into)
- In the cloned repository directory, run `npm install` to install the dependencies for Brackets
- Run `npm run build` to create the built editor files that will be used by Thimble
- Run `npm start` to start a server that will allow the editor to be accessed on [http://localhost:8000/src](http://localhost:8000/src)
- You can find out more information about setting up Brackets locally by referring to the instructions [here](https://github.com/mozilla/brackets#how-to-setup-bramble-brackets-in-your-local-machine)

### Thimble and Services

Thimble interacts with the Publish API (source managed in [publish.webmaker.org](https://github.com/mozilla/publish.webmaker.org)) to store users, projects, files and other content as well as publish user projects.

For authentication and user management, Thimble uses Webmaker OAuth which consists of the Webmaker ID System (source managed in [id.webmaker.org](htps://github.com/mozilla/id.webmaker.org)) and the Webmaker Login API (source managed in [login.webmaker.org](https://github.com/mozilla/login.webmaker.org)).

All three services along with Thimble are bundled together using Git subtrees and run together using Vagrant.
-- You can find out more information about setting up Brackets locally by referring to the instructions [here](https://github.com/mozilla/brackets#how-to-setup-bramble-brackets-in-your-local-machine)

### Installing Thimble and Services with Vagrant
The first step is to fork and clone Thimble and navigate to the cloned directory in a terminal shell.

For the first time, to start all dependent services and Thimble, simply run:

```
vagrant up
```
This process can take a while depending on your internet connection speed as it needs to download all dependencies. Once you see a log that says `Express server listening on http://localhost:3500`, you can access Thimble on [http://localhost:3500](http://localhost:3500).

You can now make changes to the Thimble source code on your system and they should be automatically reflected on [http://localhost:3500](http://localhost:3500).
Depending on your internet connection speed, this process can take a while (since it needs to download all dependencies not listed above).
Once you see `Express server listening on http://localhost:3500`, you are ready to start using Thimble on [http://localhost:3500](http://localhost:3500)!
Any changes made to the Thimble source code on your system will automatically be reflected on [http://localhost:3500](http://localhost:3500).

To stop running Thimble, simply press `Ctrl+C` twice.
To stop Thimble, simply press `Ctrl+C` twice.

To restart Thimble, run:

To restart Thimble again, run:
```
vagrant reload --provision
```
This will take a much shorter time to setup compared to the `vagrant up` command.

This will take less time to setup compared to the `vagrant up` command.

## Manual Installation
You can also setup Thimble and its needed components outside Vagrant and Virtualbox. This might be needed if you want to:
- Host your own instance of Thimble
- Cannot run virtualization software on your computer

### Prerequisites for Manual Installation
In order for Thimble to be installed correctly, the following dependencies need to be installed:

- Node.js 4.x or above (see note below)
- **Note:** The login.webmaker.org dependency needs a node version of 4.x only while all the other dependencies work with a node version of 4.x and above. We suggest installing [NVM](https://github.com/creationix/nvm) to allow the use of multiple versions of node.
- [Brackets (Bramble)](#installing-brackets-bramble)
- [Webmaker ID server](#idwebmakerorg)
- [Webmaker Publishing Server](#publishwebmakerorg)
- [Postgresql 9.4 or above (for the publish.webmaker.org dependency)](#postgresql)
- g++ 4.8 or above (for the login.webmaker.org dependency)
- [Webmaker Login Server](#loginwebmakerorg)

The following is an abbreviated guide to getting it all set up. Please see each server's README for more details.

### Manually Installing the Parts
Please note: On Windows, use ``copy`` instead of ``cp``

####Thimble
* Fork and clone https://github.com/mozilla/thimble.mozilla.org
* Run ``cp env.dist .env`` to create an environment file
* Run ``npm install`` to install dependencies
* Run ``npm start`` to start the server

####id.webmaker.org
* Clone https://github.com/mozilla/id.webmaker.org
* Run ``cp sample.env .env`` to create an environment file
* Run ``npm install`` to install dependencies
* Run ``npm start`` to start the server

####login.webmaker.org
* Clone https://github.com/mozilla/login.webmaker.org
* Run ``npm install`` to install dependencies
* Run ``cp env.sample .env`` to create an environment file
* Run ``npm start`` the server

####PostgreSQL
* Run ``initdb -D /usr/local/var/postgres`` to initialize PostreSQL
* If this already exists, run ``rm -rf /usr/local/var/postgres`` to remove it
* Run ``postgres -D /usr/local/var/postgres`` to start the PostgreSQL server
* Run ``createdb publish`` to create the Publish database

####publish.webmaker.org
* These steps assume you've followed the PostgreSQL steps above, including creating the publish database.
* Clone https://github.com/mozilla/publish.webmaker.org
* Run ``npm install`` to install dependencies
* Run ``npm run env``
* Run ``npm run knex`` to seed the publish database created earlier
* Run ``npm start`` to run the server

Once everything is ready and running, Thimble will be available at [http://localhost:3500/](http://localhost:3500/)

### Getting Ready to Publish
To publish locally, you'll need to do the following...

####Teach the ID server about the Publish server

* Run ``createdb webmaker_oauth_test`` to create a test database
* In your id.webmaker.org folder
* Run ``node scripts/create-tables.js``
* Edit ``scripts/test-data.sql`` and replace its contents with:

```sql
INSERT INTO clients VALUES
( 'test',
'test',
'["password", "authorization_code"]'::jsonb,
'["code", "token"]'::jsonb,
'http://localhost:3500/callback' )
```

* Run ``node scripts/test-data.js``
* You'll see a ``INSERT 0 1`` message if successful

####Sign In

To publish locally, you'll need an account.
* Go to [http://localhost:3000/account](http://localhost:3000/account)
* Click ``Join Webmaker`` and complete the process, you can use a fake email
* When you've created your account, click ``Set permanent password instead``
* This lets you authenticate your account without needing email
* Go back to Thimble and Log In with your new account


It's that simple! You are now ready to start using Thimble to its full potential!

Localization
----------------------

0 comments on commit dde580e

Please sign in to comment.
You can’t perform that action at this time.