<markdown>
==========================
Getting Started with Solar
==========================

------------------
First Run (Novice)
------------------

This is a less-secure but very easy way to start a new Solar project.

1. Download a [Solar-system tarball](http://svn.solarphp.com/system/download) and extract the tarball to your document root.

2. **Read the README file** for security notes.

3. Make the `sqlite/` and `tmp/` directories fully-accessible to the web server process. The easiest (but least secure) way to do this is to allow all users read/write/execute privileges:

    {{code: bash
        chmod -R 777 sqlite
        chmod -R 777 tmp
    }}

4. Browse to the installation `index.php` file. For example, if you install to
your user-specific web document root in a directory called "solar", you would
browse to:

        http://example.com/~username/solar/index.php

    You should see a "Hello World!" page.  You can also browse to ...

        http://example.com/~username/solar/index.php/hello-app

    ... and:

        http://example.com/~username/solar/index.php/bookmarks


------------------
First Run (Expert)
------------------

This is a more-secure but somewhat more complicated way to start a new Solar
project. If mod_rewrite is available and turned on, it uses a .htaccess file
for pretty URLs.

1. Place a download of the [Solar-system tarball](http://svn.solarphp.com/system/download) 
in a location on the web server **outside** the document root.

2. **Read the README file** for security notes.

3. Make the `sqlite/` and `tmp/` directories fully-accessible to the web server process. The easiest (but least secure) way to do this is to allow all users read/write/execute privileges:

    {{code: bash
        chmod -R 777 sqlite
        chmod -R 777 tmp
    }}

4. Create a virtual host on the web server and point its DocumentRoot to the
Solar-system `docroot` directory.

    For example, if you place the Solar-system For example, if place the
    system at `/home/example/subdomain/solar`, you can use Apache directives
    like the following:
    
    {{code:
        NameVirtualHost *:80
        <VirtualHost *:80>
            ServerName subdomain.example.com
            DocumentRoot /home/example/subdomain/solar/docroot
        </VirtualHost>
    }}

5. Browse to the installation using the virtual host name.


Using SVN
=========

Instead of downloading a tarball of the project, you can use `svn export` to get a copy of the Subversion trunk as it exists now, or use `svn checkout` to be able to update the system on a regular basis as Solar development continues.

{{code: bash
    # export a static copy of the current trunk
    svn export http://svn.solarphp.com/system/trunk /home/example/subdomain/solar
    
    # check out a working copy of the trunk for continuous updates
    svn checkout http://svn.solarphp.com/system/trunk /home/example/subdomain/solar
}}

-----
Nginx
-----

You can set up pretty URIs on nginx with the following code inside your server declaration:

    location / {
        root   /path/to/solar/docroot/;
        index  index.php;

        # This matches the requested file to a .css extension so it 
        # won't be processed as php even if the file is missing.
        if ($request_filename ~ ^.*\.css$) {
            break;
        }

        # Matches any file/directory/link that doesn't exist (-e), 
        # prepends index.php to the query string (assuming your 
        # index.php is at the root) so that the location below
        # matches and is handed off to the fast CGI handler.
        if (!-e $request_filename) {
            rewrite ^/(.*)$ /index.php/$1 last;
            break;
        }
    }

    # Matches a query string where index.php is at the root
    # (change if your solar system has a non empty $URIBASE)
    # and hands off those requests to the php fast CGI handler.
    location ~ ^/index\.php.*$ {
        fastcgi_pass   127.0.0.1:9000;
        fastcgi_param  SCRIPT_FILENAME  /path/to/solar/docroot$fastcgi_script_name;
        include /etc/nginx/fastcgi_params;
    }
</markdown>