Contains packages and other files for building Subscribo API backend as well as Subscribo Frontend servers

• A.1 Frontend server installation
• B.1.i Backend server installation on Homestead
• B.1.ii Backend server installation on web server
• C.1 Local Satis server configuration

You need to decide following:

• where you want to put your frontend project: /path/to/your/frontend/project/ = path/to/your/project/parent/your_frontend_project_subdirectory_name
• host name of your frontend: frontend.hostname

Notes:

• You do not need DB for frontend.
• If you already have had Vagrant box configured and updated its configuration, you might need to run vagrant reload --provision to let vagrant box find your new sites
• Add new record with frontend.hostname to your /etc/hosts if needed (you might find IP address needed for new record in path/to/your/homestead/configuration/Homestead.yaml under key ip)

In order to install into 'frontend' directory you may use this composer command (provided you have composer installed and current Laravel version is 5.1):

    composer create-project laravel/laravel --prefer-dist your_frontend_project_subdirectory_name

In development you may use .env.frontend file generated during Backend Installation for setting up environment variables:

    $ cp /path/to/your/backend/project/.env.frontend /path/to/your/frontend/project/.env
    $ vi /path/to/your/frontend/project/.env # Modify as needed (see below)

Only following environment keys are needed for frontend (you may delete the rest):

    APP_ENV=local
    APP_DEBUG=true
    APP_KEY=SomeRandomString32CharactersLong # you may reset this via php artisan key:generate

    SUBSCRIBO_REST_CLIENT_PROTOCOL=http
    SUBSCRIBO_REST_CLIENT_HOST=frontend.hostname
    SUBSCRIBO_REST_CLIENT_TOKEN_RING=simple_some_long_hash

    CACHE_DRIVER=file
    SESSION_DRIVER=file
    QUEUE_DRIVER=sync

Frontend server does not use database, so database setting are not needed.

It takes needed information from backend, for which it needs to have set connection correctly: SUBSCRIBO_REST_CLIENT_PROTOCOL, SUBSCRIBO_REST_CLIENT_HOST and especially SUBSCRIBO_REST_CLIENT_TOKEN_RING.

####### Finding out your Token ring

If SUBSCRIBO_REST_CLIENT_TOKEN_RING is not set to string starting with 'simple_' or you are getting Internal Server Error when trying to access any frontend page communicating with backend and log connected to that particular error is having something like 'Unauthorized' or 'TokenConfigurationException' you need to set this value properly.

You might find the proper token ring in Backend server database, table user_tokens, field token_ring. Be sure you select correct row, i.e. row having type SubscriboDigest connected to correct user - i.e. user having type server and connected to your service.

(First find ID of your service in services table - check that url of your service agrees with frontend.hostname, then find ID of user of type server connected to your service ID, finally find appropriate user token in table user_tokens having type SubscriboDigest and connected to your user, and copy over token_ring to .env file.)

You may also use following sql (modify its end for service with different identifier):

    SELECT `token_ring` FROM `user_tokens` JOIN `users` ON `user_tokens`.`user_id` = `users`.`id` JOIN `services` ON `users`.`service_id` = `services`.`id` WHERE `user_tokens`.`type` = "SubscriboDigest" AND `users`.`type` = "server" AND `services`.`identifier` = "FRONTEND"

You need to decide following:

• where you want to put your project: path/to/your/project = path/to/your/project/parent/your_project_subdirectory_name
• where you want to put your Homestead configuration: path/to/your/homestead/configuration
• host name of your project: backend.hostname

Optionally:

• Do you want to also make additional frontend?
• If so, host name of additional frontend: frontend.hostname

    $ cd path/to/your/project/parent

    $ git clone https://github.com/Subscribo/Subscribo your_project_subdirectory_name

    $ cd path/to/your/project/
    $ cp .env.example .env
    $ vi .env                        # modify as needed

Notes:

• Setup DB access details, if you have changed them in your vagrant box or created a special DB for this project
• Do not forget to setup 'SUBSCRIBO_REST_CLIENT_HOST' to hostname accessible from host (this is actually the host name of your backend server - backend.hostname; you need to put this also under key sites: in your Homestead.yaml)

    $ cd path/to/your/homestead/configuration
    $ vi Homestead.yaml
    $ vagrant up
    $ sudo vi /etc/hosts

    $ cd path/to/your/homestead/configuration
    $ vagrant ssh
    vagrant@homestead:$ cd path/where/your/project/is/mapped
    vagrant@homestead:$ source bin/install_backend.sh test

Note: instead of running install_backend.sh via source command, you may run it as a script, (which has an advantage on stopping on first error). To do so, run these commands instead of last line in previous script:

    vagrant@homestead:$ chmod +x bin/install_backend.sh
    vagrant@homestead:$ bin/install_backend.sh test

When using Homestead box and have compatible php installed on your host machine, you may also run some of artisan command directly from terminal of your host machine (i.e. not via vagrant ssh) To be able to run also database-related commands (such as php artisan migrate:refresh) you need to set up environment first. You may do so by creating and modifying file .env.commandline and setting up respective environment variable.

To do once:

    $ cd path/to/your/project/
    $ cp .env .env.commandline
    $ vi .env.commandline            # modify as needed (see below)

You need to modify following .env.commandline keys (see Connecting to databases in Laravel Homestead docs

APP_ENV=commandline
DB_HOST=127.0.0.1
DB_PORT=33060

Note: make sure, that whenever you change important settings in .env file (such as SUBSCRIBO_COMMON_SECRET) you need to change it in .env.commandline as well

Now, whenever you open new terminal window on your host machine and plan to run artisan commands related to DB operations, run first following:

    $ SUBSCRIBO_ENV=commandline
    $ export SUBSCRIBO_ENV

Notes:

• if you want to run DB related artisan commands from your IDE, you also might need to set environment variable 'SUBSCRIBO_ENV' to value 'commandline'
• usual error which is displayed, when you did not so, and meaning there is a problem with a connection to your DB, is:

    [PDOException]
    SQLSTATE[HY00] [2002] No such file or directory

• Setup DB access, Mail driver and access etc.
• Do not forget to setup 'SUBSCRIBO_REST_CLIENT_HOST' to hostname accessible from host

    $ cd path/to/your/project/parent
    $ git clone https://github.com/Subscribo/Subscribo your_project_subdirectory_name

    $ cd path/to/your/project/
    $ ls -A                                               # Ensure, that the directory is empty (should display nothing)
    $ git clone https://github.com/Subscribo/Subscribo .  # Note the trailing dot

    $ cd path/to/your/project/

    $ vi bin/install_backend.sh         # Modify as needed (e.g. remove things you do not want script would do)
    $ chmod +x bin/install_backend.sh   # Make script executable
    $ bin/install_backend.sh test       # Run it

Running 'composer update' would not work, if packages resource is not configured, as there are private packages used. For development you may configure local packages resource using Satis

(or modify 'bin/configure_satis.sh' )

    $ /path/to/Subscribo/bin/configure_satis.sh

Notes:

• This script is not suitable for refreshing satis configuration, only for first-time install
• It might be faster and easier to run this script from your host terminal (as opposed to vagrant ssh)
• If you want to run this script via vagrant ssh you need to make sure, that directory for satis exists prior to running a script or that script is able to create such directory (this is true also for directory for packages if it is not part of your backend project)

Important: You might need to run vagrant 'reload --provision' to let vagrant box find your new sites

    {
        "repositories": [
            {
                "type": "composer",
                "url": "http://satis.url.you.provided.to.script"
            }
        ]
    }

Notes:

• configure_satis.sh script provides similar file for you in bin/files/composer directory and provides you with a hint how to copy it over your previous configuration (if any). It is recommended that you first check the content of your current configuration before you overwrite it.
• If you intend to use composer update etc., both from your host terminal as well as from vagrant ssh, then you need to put this file into ~/.composer directory of your user on both vagrant machine as well as on host machine

Usually you may use script generated during installing Satis for updating Satis with current content of your project's vendor/subscribo directory.

    $ /path/to/Subscribo/bin/update_satis.sh

Notes:

• Hook to update_satis.sh has been added as pre-install and pre-update script, because if your would running composer update or composer install without your Local Satis server been up-to-date, you might overwrite your (recent) changes.
• When running update_satis.sh subdirectories of packages directory is cleaned from previous content, but .git subdirectory is not deleted. This is true for all files and directories starting with dot. If you rename / remove any file / directory in some package root starting with dot (e.g. .gitignore) you need to replicate your change in corresponding copy in packages directory manually.

When your Satis server is running, you can run:

    $ cd /path/to/Subscribo
    $ composer update

• These scripts are made ad-hoc. If you experience problems, you might need to do things manually. Studying provided scripts might give you some guidance.