-
Notifications
You must be signed in to change notification settings - Fork 387
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #3296 from nekodex/update-readme
Update Documentation
- Loading branch information
Showing
3 changed files
with
140 additions
and
63 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,10 @@ | ||
| # Code Standards | ||
|
|
||
| - For PHP, we adhere to [PSR-2](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md) and this will be enforced by StyleCI. | ||
| - For CSS, we use the [BEM](http://getbem.com/) conventions. | ||
|
|
||
| # React vs Laravel Blades | ||
|
|
||
| Previously, using React was generally preferred for pages which involved interaction beyond simple hyperlinks (ie. when state is present that can be modified by the user) or when real-time changes were presented to the user (ie. the state is volatile and dependant on back-end updates). Otherwise Laravel Blades were used instead. | ||
|
|
||
| However, we have since decided to move towards providing all data from Laravel as JSON and using React to consume this and perform rendering instead. The goal is to help ensure that there will a consistent data interface being used (i.e. the data/JSON is identical for what React uses and what the game client will be using via the API). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,115 @@ | ||
| # Setting up your development environment | ||
|
|
||
| There are a few different options to get started: | ||
|
|
||
| ## 1. Manual setup for experienced developers (i.e. using an existing development environment): | ||
| ### Install prerequisites | ||
| - MySQL 5.7 | ||
| - PHP 7.1+ (with curl, gd, intl, json, mbstring, mcrypt, mysql, xml and zip extensions) | ||
| - nginx (or other webserver) | ||
| - a modern version of nodejs (and npm) | ||
| - elasticsearch 5+ | ||
| - redis (not required, but you may want to use for caching and laravel's job-queue) | ||
|
|
||
| ### Clone the git repository | ||
| $ git clone https://github.com/ppy/osu-web.git | ||
|
|
||
| ### Configure .env file | ||
| ```bash | ||
| # copy the example file and edit the settings, the important ones are APP_* and DB_* | ||
| $ cp .env.example .env | ||
| $ vi .env | ||
| ``` | ||
|
|
||
| ### URL rewriting | ||
| ```nginx | ||
| # for nginx, with root set to the `public` folder of the repo | ||
| location / { | ||
| try_files $uri $uri/ /index.php?$query_string; | ||
| } | ||
| ``` | ||
|
|
||
| Consult the [laravel documentation](https://laravel.com/docs/5.5/installation#web-server-configuration) for non-nginx | ||
|
|
||
| ### Initialize database | ||
| ```bash | ||
| # this script assumes you can connect passwordless as root | ||
| $ ./bin/db_setup.sh | ||
| ``` | ||
|
|
||
| ### Install packages and build assets | ||
| ```bash | ||
| # will also install composer and yarn | ||
| $ ./build.sh | ||
| ``` | ||
|
|
||
| At this point you should be access the site via whatever webserver you configured | ||
|
|
||
| ## 2. Automated setup for Ubuntu | ||
|
|
||
| ### Create a fresh Ubuntu environment | ||
| On your server, a virtual machine, whatever. | ||
|
|
||
| ### Clone the git repository: | ||
| git clone https://github.com/ppy/osu-web.git | ||
|
|
||
|
|
||
| ### Run automated configuration | ||
| Note these script are intended to be run in a *sandboxed environment*; do not run on a shared development system without first understanding what is being done. | ||
| ```bash | ||
| $ sudo bootstrap.sh | ||
| $ ./build.sh | ||
| ``` | ||
|
|
||
| You can then run the standalone php server from inside the `public` folder: | ||
| ``` | ||
| php -S 127.0.0.1:8080 | ||
| ``` | ||
|
|
||
| ## 3. Using Docker | ||
|
|
||
| - First, install [Docker](https://www.docker.com/community-edition) and [Docker Compose](https://docs.docker.com/compose/install/), then run `docker-compose up` in the main directory. | ||
| - Due to the nature of Docker (a container is killed when the command running in it finishes), the Yarn container will be run in watch mode. | ||
| - If you use a non-standard user/group id (for example when your user wasn't the first one created on the system), you need to run the command as follows, with the env variables supplying your ids to the containers: | ||
| ```bash | ||
| _UID=$(id -u) _GID=$(id -g) docker-compose up | ||
| ``` | ||
| - Do note that the supplied Elasticsearch container uses a high (1+ GB) amount of RAM. Ensure that your system (or virtual machine, if running on Windows/macOS) has a necessary amount of memory allocated (at least 2 GB). If you can't (or don't want to), you can comment out the relevant elasticsearch lines in `docker-compose.yml`. | ||
| - To run any of the below commands, make sure you are in the docker container: `$ docker exec -it osuweb-php bash`. | ||
|
|
||
| # Development | ||
|
|
||
| ## Creating your initial user | ||
| In the repository directory: | ||
| ```php | ||
| $ php artisan tinker | ||
| >>> (new App\Libraries\UserRegistration(["username" => "yourusername", "user_email" => "your@email.com", "password" => "yourpassword"]))->save(); | ||
| ``` | ||
|
|
||
| ## Generating assets | ||
|
|
||
| Using Laravel's [Mix](https://laravel.com/docs/5.5/mix). | ||
| ```bash | ||
| # generate translations for langjs | ||
| $ php artisan lang:js resources/assets/js/messages.js | ||
| # generate routes for laroute | ||
| $ php artisan laroute:generate | ||
| # build assets | ||
| $ yarn run development | ||
| ``` | ||
|
|
||
| Note that if you use the bundled docker-compose setup, yarn/webpack will be already run in watch mode, and you will only need to run the `lang:js` and `laroute:generate` artisan commands whenever you need to regenerate these helper files. | ||
|
|
||
| ## Reset the database + seeding sample data | ||
|
|
||
| $ php artisan migrate:refresh --seed | ||
|
|
||
| Run the above command to rebuild the database and seed with sample data. In order for the seeder to seed beatmaps, you must enter a valid osu! API key into your `.env` configuration file as it obtains beatmap data from the osu! API. | ||
|
|
||
| # Development | ||
|
|
||
| ## Generating assets while developing | ||
|
|
||
| To continuously generate assets as you make changes to files (less, coffeescript) you can run `webpack` in `watch` mode. | ||
|
|
||
| $ yarn run watch |