# MG - magento 1.x tool ## Overview ### What's it? It's *mg*, swiss-knife tool for Magento extension developers and associated QA teams. This tool has two interfaces 1. Command-line interface. 2. Web interface Web interface is implemented as WSGI application. You can run it with provided `mgweb.py` script or setup your web server to drive it. ### Main features: * Install magento from distribution with optional sample data installation, including automatic sample data version detection * Install magento from local packages * Install modules by tag/revision name from BitBucket * Install modules from zip archives * Saving/restoring store state(database and files) * Create local packages from locally installed stores * Copy extensions configuration between stores * Fixing store installation permissions, cache, etc * Setting administrator password * Encrypting/Decrypting values, using store's secret key * Removing magento installation with DB cleanup ## Requirements * Python 2.6+ with following packages installed * Flask (for web face) * Jinja2 (also for web face) * markdown2 (for displaying readme in web interface) * lxml * mercurial(for mercurial and Bitbucket extensions repositories support) * MySQL console client with mysqldump installed * PHP command-line interpreter ## Usage ### Installation 1. Install python and required packages. If you use virtualenv, use this. Single trick to install all required stuff: `pip install Flask Jinja2 markdown2 lxml mercurial flask-restful` 2. Checkout from VCS: `hg clone https://your_user_name@bitbucket.org/aheadworks/mg` 3. Rename provided config.ini.dist to config.ini and change settings(see below) 4. Make mg.py and mgweb.py executable: `chmod +x mg.py; chmod +x mg.py` ### Installation as WSGI application This instructions are for nginx and uwsgi. #### nginx site configuration upstream flask_serv { server unix:/tmp/flask-mg.sock; } server { listen 8080; server_name autotest.vm; uwsgi_read_timeout 3600; uwsgi_send_timeout 3600; location / { uwsgi_pass flask_serv; include uwsgi_params; } } #### uwsgi app configuration /tmp/flask-mg.sock /path/to/mg/ mgweb.mgweb:app python27 ## Before you continue You need to understand some basic terms used inside **mg**. ### Pool Pool is local directory, where **mg** stores it's own data like backups of your stores, local Magento distributives, sample datas and so on. It is required my **mg** to have a pool. Pool is **not** web server root for your magento installations, it also doesn't contain any MySQL databases and so on. ### Installer Installer is internal part of **mg**, it drives all Magento installations performed by **mg**. It requires to have knowledge about: * Web server root to deploy files to correct location * Privileged MySQL access to create databases for stores it install * Some settings of web server running magento installation. First of all it needs to know URL that must be set for installed store. ### Distro source Stores magento distributives. One source is always local and located inside pool. You can add as many remote sources as you want, naming the sections in config with **dist_source_** prefix. [dist_source_community_lan] name=Storage for community versions on storage.vm download_url=http://storage.vm/magento/dist/community/magento-{version}.tar.gz list_url = http://storage.vm/magento/dist/community upload_url=sftp://uname:password@storage.vm/var/www/magento/dist/community/magento-{version}.tar.gz * name - name of source * download_url - url to download version from source * list_url - not required. **mg** can parse output of this url to get available installations. Pages like apache/nginx directory index is ok. * upload_url - not required. If specified **mg** can upload package from local source to remote one, to share it between your team. Only sftp supported by the moment. ### Extension repository Basically said repository is where your extensions stored. It can be bitbucket/mercurial repository, **mg** knows what to do about it. If more than one repository is configured, **mg** will poll then one by one with desired extension until success. ## Configuration Before using **mg** you have to configure it. * **pool** * **root** - path to special directory, containing sample datas, distibutives and other data * ***installer*** * **stores** - basically it is your server WebRoot or subfolder under web server root. * **base_url** - URL set for installed store. You can use variables here: * {name} - store to be installed name * {host} - full qualified domain name. E.g. host.com or mymachine.dev * **secure_base_url** - equal to base url, but used for SSL url * **session_save** - where installed store will save session files. Recommended value is files * **use_rewrites** - if rewrites are supported by your web server. Allowed values are yes or no * **db** * **host** - database host * **root_user** - root or other priveleged user with permission to create and drop databases * **root_password** - password for this user * **repository_xxx** Repositories storing extensions. Repositories are added by putting them to special sections which names start with repository_ * **user** - repository user * **password** - user password * **type** - repository type. Currently only bitbucket is supported * **default_vendor** - default vendor for bitbucket accounts. E.g. if all extensions are located under http://bitbucket.org/yourcooluser/some_extension, you can specify yourcooluser as default vendor and mg will add it automatically to all extension codes w/o vendor specified ### Setting up BitBucket repository Open your config file and add section [repository_bitbucket] description=My Cool repository user=butbucket_username password=bitbucket_password type=bitbucket default_vendor=bitbucket_username * default\_vendor is prefix added to all repositories searches w/o bitbucket account set. So, if all your extensions are stored under your personal account like https://bitbucket.org/bitbucket\_username and path to your extensions is something like https://bitbucket.org/bitbucket\_username/cool\_extension, you can setup default\_vendor to be bitbucket\_username, and setup your extension like cool-extension, not bitbucket\_username/cool\_extension * you can set no password here. Mg will try to reach repository by SSH protocol then, supposing you've set up deployment keys at bitbucket account. *Important*: Note that before using SSH-based access in mgweb, you have to accept bitbucket's fingerprints. Get more info at [atlassian readme](https://confluence.atlassian.com/display/BITBUCKET/Use+the+SSH+protocol+with+Bitbucket#UsetheSSHprotocolwithBitbucket-KnownhostorBitbucket%27spublickeyfingerprints) ### Setting up magento and sample data repositories You can use any protocol, supported by urllib in repositories URL configuration. E.g.: * file:///path/to/my/local/repo/magento-{version} * http://myteam.developer.com/magento/dists/{version}.tar.gz * ftp://user:password@mysecretftp.com/magentos/{version}/custom.tar.gz If you have two or more file name rules at your repository, you can configure several sources for that. MG will look for archive in all repos one by one, until success: * http://myteam.developer.com/magento/dists/magento-{version}.tar.gz * http://myteam.developer.com/magento/dists/enterprise-{version}.tar.gz ## Basic usage mg.py [command] [command_option1] [command_option2] ... Commands list: * **create_dist** Create distributive package from installed store * **delete** Delete store * **install** Installs store from release with optional sample data installation * **installext** Install extension from repository to specified store. * **list** List all installed stores * **restore** Restore saved state for store * **save** Save current state for store * **heal** Repair store files permissions, clear cache and sessions * **setadmin** Set administrator login and password * **extcfgsave** Save extension configuration(all related tables and system configuration values) * **extcfgload** Deploy saved extension configuration to installed store * **encrypt** Encrypt string using store's secret key * **decrypt** Decrypt hash using store's secret key ### Installation of store The following command will install magento 1.7.0.2 as *mytest* with sample data version 1.6.1.0: ./mg.py install mytest 1.7.0.2 1.6.1.0 This will install 1.7.0.2 to *mytest* with latest sample data available for 1.7.0.2: ./mg.py install mytest 1.7.0.2 latest You can setup several stores with common configuration: ./mg.py install mytest,myothertest 1.7.0.2 latest ### Installing extensions This will install extension from BitBucket/Mercurial repository(if configured) vendor/extension to store *mytest*. "stable" postfix mean "take latest tagged revision after tip". ./mg.py installext vendor/extension-stable mytest] If no postfix is specified, then latest revision will be installed. You can set exact version by specifying it in postfix. Installation from ZIP is also possible: ./mg.py installext /path/to/my/file.zip mytest Or even install multiple extensions from different sources at once ./mg.py installext /path/to/my/file.zip,vendor/extension-stable mytest ### Saving and restoring stores states To save store state, including all files and database for store *mytest* as *mycoolstate*: ./mg.py save mytest mycoolstate To restore store state, including all files and database for store mytest from mystate: ./mg.py restore mytest mycoolstate ## Built-in web server(experimental) To run web-server you need Flask installed. After that run ./mgweb.py And it will run at port 5000 ## Getting help Run *mg* without options and it will output list of supported commands. Run *mg* with command, but w/o options and it will output command's options ## Report bugs and suggest new functionality Use Bibucket issue tracker to post new issues. ## Using REST API mg supports REST API calls when running in server mode as well. ### /api/v1/stores #### GET Returns list of stores installed #### POST Installs store. Params: * 'store_name', type=str * 'store_version', type=str * 'sample_data', type=bool ### /api/v1/stores/store_name #### GET Get store info #### DELETE Deletes store ### /api/v1/stores/store_name/extensions #### POST Installs extension from zip file to selected store, or installs extension by name from repositories. * 'extension' * 'file'