Installing and Configuring Pico

Composer

Do you have shell access to your webserver? If so, try Composer!

Using Composer to install Pico provides a great user experience. Composer makes maintaining and updating your Pico install a breeze.

We’d really recommend you try it!

Simply run the following commands to install Composer, then use Composer to install Pico for you.

$ curl -sSL https://getcomposer.org/installer | php
$ php composer.phar create-project picocms/pico-composer pico

That’s it! You’ll thank us (and Composer) when it’s time to update!

(It’s as simple as running php composer.phar update in your Pico folder.)

Pre-Bundled Release

Not interested in an automated solution? That’s okay, you can install Pico manually too.

Download Pico

You can always find Pico’s Latest Release on our GitHub Page.

This pre-bundled release comes with all the dependencies necessary for Pico to run.

Simply upload the extracted files to the httpdocs directory (e.g. /var/www/html) of your server.

If you’re using Apache, there’s also an included .htaccess file provided for automatic configuration. If you’re running Linux or macOS, double check that you’ve uploaded this file, as it likes to hide!

Git

Using Pico together with Git, you can create a powerful, version controlled, and perhaps even collaborative workflow. The possibilities are endless!

To get you started, Pico has a ready to go Composer starter project you can fork right on on GitHub!

Our recommended Git workflow is:

1. Fork the starter project on GitHub. (If you’d rather not use GitHub, just clone it locally and manually add your new remote to the repo.)

2. Clone the fork to your local computer. Add whatever assets, content, plugins, and themes you’d like and commit them to the repo. Push the changes back to GitHub (or your own remote).

3. On your webserver, navigate to your httpdocs folder. Simply run the following commands to install Composer, then use Composer to install Pico’s dependencies for you (substituting your own Git remote if applicable).

    $ curl -sSL https://getcomposer.org/installer | php
    $ git clone https://github.com/<YOUR_USERNAME>/<YOUR_REPOSITORY> pico
    $ php composer.phar --working-dir=pico install
   

4. Next time you commit updates your Pico site repo, just run git pull in this folder on your webserver to update it. You can even update Pico and its dependencies with a simple php composer.phar update.

Git (Development)

Our recommended development workflow is to start with Pico’s Composer starter project and use Git to pull in all of Pico’s components as “local packages” for Composer.

This is a bit more involved than any other installation method, and of course also implies you’ll be using the current development version of Pico, which is likely unstable and not ready for production use!

1. On your webserver, navigate to your httpdocs directory and make a new folder for Pico (e.g. /var/www/html/pico). Download and extract Pico’s Composer starter project into the workspace directory:

    $ curl -sSL https://github.com/picocms/pico-composer/archive/master.tar.gz | tar xz
    $ mv pico-composer-master workspace
   

2. Clone the Git repositories for all Pico components (Pico’s core, Pico’s Default Theme and the PicoDeprecated plugin) into the components directory:

    $ mkdir components
    $ git clone https://github.com/picocms/Pico.git components/pico
    $ git clone https://github.com/picocms/pico-theme.git components/pico-theme
    $ git clone https://github.com/picocms/pico-deprecated.git components/pico-deprecated
   

3. Update the composer.json of your development workspace (i.e. workspace/composer.json) to instruct Composer to use the local Git repositories as replacement for the picocms/pico (Pico’s core), picocms/pico-theme (Pico’s Default Theme) and picocms/pico-deprecated (the PicoDeprecated plugin) packages.

    {
        "repositories": [
            {
                "type": "path",
                "url": "../components/pico",
                "options": { "symlink": true }
            },
            {
                "type": "path",
                "url": "../components/pico-theme",
                "options": { "symlink": true }
            },
            {
                "type": "path",
                "url": "../components/pico-deprecated",
                "options": { "symlink": true }
            }
        ],
        "require": {
            "picocms/pico": "dev-master",
            "picocms/pico-theme": "dev-master",
            "picocms/pico-deprecated": "dev-master",
            "picocms/composer-installer": "^1.0"
        }
    }
   

4. Download Composer and run it with the install option:

    $ curl -sSL https://getcomposer.org/installer | php
    $ php composer.phar --working-dir=workspace install
   

That’s it! You’re now running the development version of Pico.

By the way, you can also find all of Pico’s components on Packagist.org: Pico’s core, Pico’s Default Theme, the PicoDeprecated plugin and Pico’s Composer starter project.

Nextcloud

Pico for Nextcloud offers a powerful combination of admin features, like those you’d find in a traditional CMS.

If you’re already running Nextcloud on your webserver, you can install Pico as a Nextcloud App and take advantage of their combined features.

Just look for Pico CMS in Nextcloud’s App Store. Hit the “Download and Enable” button and you’re done!

You can then configure Pico within Nextcloud’s settings.

You’ll find Pico’s configuration divided between Nextcloud’s “Personal” and “Administration” sections.

Administration allows you to add custom themes, plugins, and templates to Pico, as well as tweak some advanced settings.

Each Nextcloud users also has their own Personal section, where they can configure their own personal Pico website.

Apache

If you’re using Apache, you’re in luck: Our included .htaccess file will take care of the configuration for you automatically.

If you have any issues, just make sure that both mod_rewrite and .htaccess overrides are enabled.

Troubleshooting (Tentative heading)

If you’re getting 404 Errors or if Pico’s still adding ? to your URLs, you’ll want to make sure Apache is configured right. The location of Apache’s config file (or files) depends on your Linux Distribution (for example, /etc/httpd/httpd.conf, /etc/httpd/conf/httpd.conf, or /etc/apache2/httpd.conf).

Your config file should have a line similar to LoadModule rewrite_module modules/mod_rewrite.so in it enabling mod_rewrite. Make sure this line isn’t commented out!

You’ll also want to make sure that .htaccess overrides are allowed, by setting AllowOverride All in either your global Apache config or in your virtual host config file (often located in a subfolder of your Apache config, such as vhosts or sites-available).

If you get a 500 Internal Sever Error, try removing the last line of .htaccess, which declares some extra Options. For security reasons, this declaration disables Indexes and MultiViews to prevent visitors from being able to browse your raw files. However, if your web host has configured Apache to not allow option setting, this line will cause it to throw a 500 Error.

In rare cases where you have URL Rewriting working, but Pico is still adding ? to your URLs, you can manually override Pico’s behavior by setting rewrite_url: true in your config.yml.

Nginx Learn more…

If you’re using Nginx, configuration is a little more involved than Apache. We have an entire Nginx Guide to help walk you through the process.

The following configuration excerpt is somewhat of a “tl;dr” version of a very extensive topic. It should provide the bare minimum configuration you need for Pico. If you have any trouble, please read all of the aforementioned Nginx Guide. For additional assistance, please refer to our “Getting Help” page.

location ~ ^/pico/((config|content|vendor|composer\.(json|lock|phar))(/|$)|(.+/)?\.(?!well-known(/|$))) {
    try_files /pico/index.php$is_args$args =404;
}

location /pico/ {
    index index.php;
    try_files $uri $uri/ /pico/index.php$is_args$args;
}

The first block of this example is for denying access to Pico’s internal files. This is recommend for security reasons, and is included in .htaccess for our Apache users.

The second block provides the URL rewriting scheme.

You’ll need to adjust the path of /pico in this example to match your own Pico installation directory.

Additionally, you’ll need to either add fastcgi_param PICO_URL_REWRITING 1; to your PHP location block or specify rewrite_url: true in your config.yml.

Lighttpd

Pico runs great on Lighttpd. The following config should provide the bare minimum configuration you need for Pico.

url.rewrite-once = (
    "^/pico/(config|content|vendor|composer\.(json|lock|phar))(/|$)" => "/pico/index.php",
    "^/pico/(.+/)?\.(?!well-known(/|$))" => "/pico/index.php"
)

url.rewrite-if-not-file = (
    "^/pico(/|$)" => "/pico/index.php"
)

The first block of this example is for denying access to Pico’s internal files. This is recommend for security reasons, and is included in .htaccess for our Apache users.

The second block provides the URL rewriting scheme.

You’ll need to adjust the path of /pico in this example to match your own Pico installation directory.

Additionally, you’ll need to specify rewrite_url: true in your config.yml.

Caddy

Pico runs great on Caddy. The automatic SSL capabilities of Caddy make it a great choice for your Pico site. The following config should provide the bare minimum configuration you need for Pico.

# Caddy Config go here. ;P

The first block of this example is for denying access to Pico’s internal files. This is recommend for security reasons, and is included in .htaccess for our Apache users.

The second block provides the URL rewriting scheme.

You’ll need to adjust the path of /pico in this example to match your own Pico installation directory.

Additionally, you’ll need to specify rewrite_url: true in your config.yml.