You are here

Quick installation guide for beginners

This document is for average computer users running Microsoft Windows as their operating system at home. People using OSX or GNU/LInux will need to adapt a few details to their own requirements - but that should be very straightforward. Note that we are referring to your OS at home - from which you will be uploading Friendica to a server. That server will almost certainly be running Linux. But here's the good news: You can even get by without knowing that!

 

 

 

There are various ways of installing Friendica and various environments for it. Some are more complex than others. The benefit is that they are usually also more flexible. For instance, they may let you run arbitrary other Internet applications alongside Friendica. If you are the kind of user who doesn't mind a bit of complexity, you can find documentation for more advanced installation routines on our Resources page ( http://friendica.com/resources ) - or by clicking from there to our Wiki on Github.

But the instructions given in this document are for a basic, personal site using what is called a shared host. That means you will be easily creating a site you can use for yourself and your family, or possibly a couple of friends. You will be using the kind of hosting deal that is often called web hosting - the type that allows you to put pages on a web server and show them to the world. This type of deal doesn't expect you to manage the server itself, which requires a bit more expertise. It usually doesn't assume that you are happy using tools made for geeks, either.

So we will be installing Friendica in a way that avoids things like command-line interaction. You will only be using graphical tools for this job: a web browser, an FTP program (to transfer the files to your server) and possibly also a text editor.

 

What you need before you start

Your shared hosting account will need to meet the prerequisites described in this document: http://friendica.com/node/18 . Don't worry if you don't understand it. If you already have a hosting deal, ask the provider's support staff to read it. If you don't already have a hosting provider, choose one from the list or ask any other provider's sales staff to check for compatibility by reading the document.

We are also assuming that your hosting provider gives you a web interface for database creation and management. Don't worry too much about this, either. We aren't going to be doing anything complex with the database - just creating an empty one with a few mouse clicks. The vast majority of hosting providers make simple, browser-based tools available for this purpose.

 

A decision you need to make first

Friendica should be installed in a domain of its own or in a subdomain. A domain would be something like yourself.com, whereas a subdomain might be friendica.yourself.com.  What won't work very well is a mere subdirectory, e.g.: yourself.com/friendica.

Make a decision now, because you are going to have to stick with it. If you choose a full domain, you can skip to the next section of this document already. If you choose a subdomain you will need to discover how to create it. Your hosting provider will almost certainly provide a browser-based routine for this - i.e. a web interface to manage your account. Using this interface, you first create a folder/directory in which to install Friendica, then a subdomain that points to this directory. Example: friendica.yourself.com could point to a directory called friendica or social (or anything that takes your fancy).

 

Getting the tools you need for installation

If all goes well, we will only be needing one tool for this job: an FTP client. You can download a fairly intuitive free one for use with Windows or OSX. It's called Cyberduck: http://cyberduck.ch/

Just in case you don't know what an FTP client is: You use it to transfer files from one computer to another - e.g. from your computer at home to your server.

If the going gets a little tougher (but not very much), we may also need an application to edit a few lines in a configuration file. We will use WordPad (ships with Windows itself) to edit that file - if any editing is required.

 

Getting Friendica

You can download Friendica in two zip (compressed) files.

The first contains the core system and can be found here: http://github.com/friendica/friendica/archives/master . Be sure to grab the .zip version and not .tgz - and also go for the latest version. 

You will also be needing the addons - not all of them are optional for what we are doing here. Find them on this page: http://github.com/friendica/friendica-addons

(The addons are slightly less conspicous on their respective page than the core system. Look for the zip file in the top left corner.)

Now put those two zip files on your Windows desktop and unzip them.

Then rename the addon folder you now see. It will be called something like friendica-friendica-addons-19b264a. Simply called it addon (no s) and put it inside the main Friendica folder you just unzipped (there is no need to rename that one).

 

Uploading Friendica

Run your FTP client. We'll assume you are using Cyberduck. Press the button at the top left to open a connection to the server.  Then enter the details for your account, as received from your provider: Server (probably your own domain name), username and password. Finally, press connect.

 

If nothing shows up in the main window, try toggling a few of the options given (passive mode, perhaps). If that doesn't work, try another protocol - FTP-SSL or SFTP. If nothing at all does the trick (very unlikely), phone your provider and ask for help.

Once you are connected to your shared hosting account, either navigate to your web root directory (if you are using a separate domain) or navigate to the directory you created for your subdomain. If you are unsure what your web root directory is, search your provider's help pages for more information. If even that fails to make things clearer, your provider certainly deserves a phone call.

Then press the Upload button and navigate the next dialog box to the Friendica folder on your desktop - select everything in it and upload. If you are warned that you are overwriting something,  allow it.

Wait until uploading is finished. Then move on and create a database.

 

Creating the database

Something disappointing is about to happen - we are going to leave you alone now! But don't worry!

To create a MySQL database for Friendica, you are going to use whichever web interface your provider makes available for that purpose. It should not be hard to discover. Usually, there is a single web tool for everything you need to do with your account - and database creation will be an available option from there.

Since there are various visual (web) routines for database management in use among providers, we can't tell you exactly how to create a database. We can only predict that it will be easy - not a geek job.  But there is one thing we must ask you to do. When you have successfully created that empty database, we will be needing the following details: hostname, username, password, database name. Be sure to jot them down or copy them to a text document. Additionally, you can simply leave the browser window or tab with those details open as you complete the next step.

Just to reassure you, here is a picture of the database creation panel at Dreamhost:

 

That's hardly very daunting, is it?


Completing the installation process

Visit your website with a web browser by simply going to the URL you planned for your site. It may take a while to load during this installation run. But when it's there, just follow the instructions you see in your browser. These instructions will include entering the database details.

If there are any error messages, attempt to follow the advice given. Also go the the Troubleshooting section at the bottom of this document. If your problems persist, use an existing account or join one of our test servers and go to the Friendica Support forum for help. You can find the test servers here: http://friendica.com/node/31 Friendica Support is here: http://helpers.pyxis.uberspace.de/profile/helpers

Note that you will get a message that saying 'IMPORTANT: You will need to [manually] setup a scheduled task for the poller.' But you can ignore this one, since we're going to use easy plugins for the time being.

If all goes well, on the other hand, installation will end with the creation of your personal account as a user and the admin of your new Friendica site.

 

Configure your account basics

After the above process you should receive an email with your provisional password. Log on using your nickname (created in the previous step) or email address and that password. Go to Settings and change the provided password to one of your choice. Then visit the Site section of the Admin menu to close registration access to your new site - this is a choice you can revise later. For a small site like the one we are aiming at, the wisest policy may be to open for registration very briefly every time a family member or friend wants to acquire an account. You can close the site again as soon as that person has registered.

If you are new to Friendica, check out your Help menu for the New User Quick Start, which will walk you through the basics of user-side configuration and the content/contact model.


Activating scheduled tasks

Please do one more thing before you consider installation complete. Go to your Admin menu and then to Plugins. Activate external cron and Poor Man Cron. Since we are not configuring so-called cron jobs on the server's command line, we need these two utilities to ensure that essential tasks are conducted automatically at sensible intervals.

After activating the plugins, Poor Man Cron will initially be the one actually doing the work - like polling other services for new content. It's a very inefficient and sluggish option, so you should deactivate it as soon as you can get external cron working properly. 

To do this, search the web for a "free cron" provider who will let you run jobs frequently. Here is one example: setcronjob.com

Sign up for a free account and create a so-called cron job (a scheduled task) to run every 10 or 15 minutes. Setcronjob.com has a very easy web interface for this. All you need to know is the URL to call. Use this:

https://YOURSITE/extcron (replacing YOURSITE with the URL of your Friendica site)

Set notifications to "when cron fails".

(Note: Other free cron services may require a complete command to run - something like this: wget https://YOURSITE/extcron > /dev/null 2&$1)

Now deactivate Poor Man Cron.

If you are slightly more experienced or know someone who is, you can consult the installation instructions in your new site's help pages and set up a real cron job - this is your best option. Should you do this at a later date, be sure to deactivate both cron plugins accordingly. However: Not all shared hosting providers will let you run cron jobs, so you may be forced to stick with external cron.


Updates

There is an admin page for updates. If major, stable updates are available, you will be able to install them by mouse click there. Later on, as you meet other Friendica admins, you may want to update more frequently, using a different method. But there is plenty of time to discover more about that as you get used to the system.

If the simple update method (per mouse click) fails, just back up a filed called .htconfig.php (as a precaution, but note the dot) and delete everything else in your Friendica and addon directories using your FTP client. Then upload the new version as for a fresh install. Except for a few technical details (contained in .htconfig.php), all your personal settings are stored in the database anyway, so nothing will be lost.

If you for any reason ever changed a file called .htaccess, back that one up too. When everything else is updated, use the backed up version of that file instead of the new one.

In the event of you making a mistake that disables your site, don't worry. Your database is almost certainly safe. Get yourself an temporary account on one of the test servers (http://friendica.com/node/31) and contact Friendica Support for help (http://helpers.pyxis.uberspace.de/profile/helpers).


Troubleshooting

Two main things might go wrong during installation.

a) A file called .htconfig.php (note the dot) didn't get created or wasn't created properly.

b) The database wasn't set up properly.

These two things often go hand in hand. In most cases, the installation routine will notice the glitch and continue. At the end, you will be given some configuration code to copy and paste into a file you create and name  .htconfig.php (the preceding dot is important). Then you simply upload that file to your server and the problem is solved.

In rare cases, you might need to fix things manually. To do so, open the Friendica folder on your desktop. Find a file called htconfig.php and rename it to .htconfig.php (with the dot preceding the rest of the name).

Open it with WordPad (rather than notepad) and look for these lines:

$db_host = 'your.mysqlhost.com';
$db_user = 'mysqlusername';
$db_pass = 'mysqlpassword';
$db_data = 'mysqldatabasename';

Carefully enter your database details here.

Also edit the line for the admin email address and enter the one you want to use (your own):

$a->config['admin_email'] = 'your@mailaddress';

Then save the file and upload it to the server. If the server already has that file after all, don't worry. Overwrite it.

Next, use the database management tool your hosting provider offers to check whether the database already has a structure. If so, find the menu item that lets you empty (called 'dropping') the database tables. Then upload the database structure from a file in the Friendica folder on your desktop, called database.sql. Discovering how to do this with your provider's database management tool ought to be fairly intuitive.

Now revisit your site to complete installation.

 

Rarer troubleshooting

There is one more thing that can go wrong with in rare cases. It won't affect installation or cause your site to fail entirely. But if it happens, you will notice huge delays in content exchanges with other sites on the distributed network. If this occurs, find out the correct path to the PHP command line processor from your provider (help files or phone call).

Then download .htconfig.php from your otherwise functioning site. Don't use the virgin file from that desktop folder any more (the folder should really have been discarded by now anyway).

Find these lines:


// Location of PHP command line processor

$a->config['php_path'] = 'php';

 

Enter the path you have discovered:

$a->config['php_path'] = '/path/to/php';

Upload the revised version of .htconfig.php.

 

Theme by Danetsoft and Danang Probo Sayekti inspired by Maksimer