From b643d8ff6af990815fc6d731477da3ccab6cc9f9 Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 14 Jun 2016 15:12:35 +0100 Subject: [PATCH] Update README.md To reflect the fact that you can now sensibly deploy from a package (ie. be able to configure the app). Make the first thing be downloading a prebuilt package so people who only read the first part don't end up running npm start in production and complain about needing npm. --- README.md | 66 +++++++++++++++++++++++++++---------------------------- 1 file changed, 33 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index 7a45339f6..332b38529 100644 --- a/README.md +++ b/README.md @@ -3,8 +3,23 @@ Vector/Web Vector is a Matrix web client built using the Matrix React SDK (https://github.com/matrix-org/matrix-react-sdk). -Getting started +Getting Started =============== +Vector is a modular webapp built with modern ES6 and requires and npm build system to build. +Instructions for building are below, but building from source shouldn't be necessary +for simple deployments. + +1. Download the latest version from https://vector.im/packages/ +1. Untar the tarball on your web server +1. Move (or symlink) the vector-x.x.x directory to an appropriate name +1. If desired, copy `config.sample.json` to `config.json` and edit it + as desired. See below for details. +1. Enter the URL into your browser and log into vector! + +Building From Source +==================== + +If you do wish to build vector from source: 1. Install or update `node.js` so that your `npm` is at least at version `2.0.0` 1. Clone the repo: `git clone https://github.com/vector-im/vector-web.git` @@ -13,19 +28,21 @@ Getting started 1. If you are using the `develop` branch of vector, you will probably need to rebuild one of the dependencies, due to https://github.com/npm/npm/issues/3055: `(cd node_modules/matrix-react-sdk && npm install)` -1. Start the development builder and a testing server: `npm start` -1. Wait a few seconds for the initial build to finish (the command won't - terminate: it's running a web server for you). -1. Open http://127.0.0.1:8080/ in your browser to see your newly built Vector. +1. Configure the app by modifying the `config.json` file (see below for details) +1. `npm run package` to build a tarball to deploy. Untaring this file will give + a version-specific directory containing all the files that need to go on your + web server. -With `npm start`, any changes you make to the source files will cause a rebuild so -your changes will show up when you refresh. This development server also disables -caching, so do NOT use it in production. +Note that `npm run package` is not supported on Windows, so Windows users can run `npm +run build`, which will build all the necessary files into the `vector` +directory. The version of Vector will not appear in Settings without +using the package script. You can then mount the vector directory on your +webserver to actually serve up the app, which is entirely static content. -Configuring +config.json =========== -Configure the app by modifying the `config.json` file: +You can configure the app by modifying the `config.json` file: 1. `default_hs_url` is the default home server url. 1. `default_is_url` is the default identity server url (this is the server used @@ -33,31 +50,13 @@ Configure the app by modifying the `config.json` file: registering with an email address or adding an email address to your account will not work. -You will need to re-run `npm run build` after editing `config.json`. - -Deployment -========== - -On a Unix-based OS, run `npm run package` to build a tarball package. Untaring -this file will give a version-specific directory containing all the files that -need to go on your web server. - -The package script is not supported on Windows, so Windows users can run `npm -run build`, which will build all the necessary files into the `vector` -directory. Note that the version of Vector will not appear in Settings without -using the package script. You can then mount the vector directory on your -webserver to actually serve up the app, which is entirely static content. - Development =========== -For simple tweaks, you can work on any of the source files within Vector with -the setup above, and your changes will cause an instant rebuild. - -However, much of the functionality in Vector is actually in the -`matrix-react-sdk` and `matrix-js-sdk` modules. It is possible to set these up -in a way that makes it easy to track the `develop` branches in git and to make -local changes without having to manually rebuild each time. +Much of the functionality in Vector is actually in the `matrix-react-sdk` and +`matrix-js-sdk` modules. It is possible to set these up in a way that makes it +easy to track the `develop` branches in git and to make local changes without +having to manually rebuild each time. [Be aware that there may be problems with this process under npm version 3.] @@ -102,7 +101,8 @@ Finally, build and start vector itself: + 1013 hidden modules ``` Remember, the command will not terminate since it runs the web server - and rebuilds source files when they change. + and rebuilds source files when they change. This development server also + disables caching, so do NOT use it in production. 1. Open http://127.0.0.1:8080/ in your browser to see your newly built Vector. When you make changes to `matrix-js-sdk` or `matrix-react-sdk`, you will need