Since many people new to XOOPS start in the forums and many basic questions get asked repeatedly, I thought I would break down how I approach starting a new site using Xoops.

Day 1 - XOOPS Core
Q: Which version do I download?
A: The latest version is found by clicking Download XOOPS is the Community menu or the Download Now! in the Welcome area at the top of the home page. Currently, 2.0.16 is the latest version. There is another branch (2.2.x), but it will be recombined in with 2.0.16 in an upcoming release, so stick with 2.0.16 for now.

Read this page and this article

Once you have downloaded the latest version, unzip it to a folder on your computer. You will see 4 folders and 3 files - take some time to read the release_notes.txt.

That's all for Day 1!

Day 2 - About the Core
If you've extracted the files from the core download and looked at them, there is only one folder that will become part of your new site - /htdocs. The contents of this folder will be uploaded to your hosting provider, the other folders are for your information, mostly.

The /docs folder contains an HTML page and screenshots outlining the installation process. The /upgrade folder is for people who are upgrading an existing XOOPS installation to the version contained in this download. There is also an /extras folder for backwards compatibility with some modules (we'll get to these in a minute) that were making direct use of some of the XOOPS core information.

The XOOPS core is like your computer's operating system - it provides a common foundation for other programs (modules) to perform the tasks they are designed to do. And, like most operating systems, there are some basic add-ons you will want for a stronger foundation - a security module (antivirus and firewall), some additional editors (word processors), a method to backup your site's data, and some diagnostic tools for managing your site. So - you will need to download these to add to your core installation.

Where do you go to download these add-ons? Well, there are a variety of locations because they are developed and maintained by a variety of people. Xoops.org is undergoing an effort to better present those options in one location - watch for updates on that. For now, here's what to look for and where to look:

Security (the Protector module v3.0) Note: bookmark this page - you'll be back for more of his modules later
Backup (DB Backup and Restore)
Editors (Frameworks and Xoopseditors v1.10) Note: You'll also want to bookmark the download page for these - there are some other great modules available from there
Diagnostics (XoopsInfo v2.12)

Download them and extract them into separate folders, for now. Each of these additional downloads will come with a readme file that explains how to add them to the core. Some of them are modules and some are core additions. We'll talk about the difference in the next entry.

After you have downloaded and extracted these, go back an review the folder structure under the /htdocs folder of your XOOPS core download - it's an important part of succeeding in customizing your XOOPS installation.

Great Idea!

Great idea skenow.
Some remarks : The CONTENT (files) of the folder /htdocs must be uploaded to the root (www/ or htdocs/) of your site.

The backup module did not work on some sites I had, for these I use a stand alone utility, mysqldumper that you can find here : http://www.mysqldumper.de/en/

The editor package is for the modules of phppp, doesn't work on all other modules.

Note: I have edited Day 2 to clarify the contents of the /htdocs folder will get uploaded to your server. This will be covered more during the post about moving your site online. Thank you svaha for mentioning that.

Throughout this series there will undoubtedly be other opinions about which modules or extensions or offline tools are preferable or recommended. Since this is focused on starting a new XOOPS site, I will recommend those which I have found that do not require (or require minimal) editing of the core or other modules - that is an advanced topic. In most cases, I will only provide information about the various options for a category and allow the user to select which suits their needs best.

Day 3 - Piecing it together
So far, you have downloaded the XOOPS core and extracted it to your computer, along with a few modules and some extensions. Now we need to start to piece together the various parts.

Open your XOOPS core folder and then navigate to the /htdocs folder. There you will see 12 other folders -
-/cache
-/class
-/extras
-/images
-/include
-/install
-/kernal
-/language
-/modules
-/templates_c
-/themes
-/uploads
There will also be other files in this directory, most notable mainfile.php

/cache and /templates_c are directories used by XOOPS to store temporary files generated by the core and various modules, so these will need to be 'writable' (more on this later - sorry to keep saying this). /uploads stores files that get uploaded to your site - pretty simple. It also needs to be writable

The /install folder will only be used during the installation of your site, and you will be instructed to delete this after you have completed the installation.

The /themes folder stores the different themes (looks, styles, or skins) you will use to customize your site.

The /modules folder stores all the modules (programs) you will add to your site.

Of the files you downloaded yesterday, 2 are extensions to the core (Frameworks and xoopseditor) and the others are modules. They all contain a file that explains how to add them to your site. Here it is in a nutshell -
1. The /Frameworks folder gets copied into the /htdocs folder of the XOOPS core (it becomes the 13th folder in /htdocs)
2. The /xoopseditor folder gets copied to the /htdocs/class folder (it becomes the 7th folder in /htdocs/class)
3. The /backup folder gets copied to the /htdocs/modules folder
4. The /xoopsinfo folder gets copied to the /htdocs/modules folder

I have not explained where the folders from Protector need to get copied - this module is one of the first to make use of a method to make your XOOPS site more secure. That will require some special attention and we'll talk about that next when we talk about the information in mainfile.php.

So far, the modules and extensions you have downloaded and begun to add to your site are primarily administrative in nature. The features your visitors will expect - news, photo galleries, downloads, links, forums, wikis, blogs, games, and many more - will come when you add modules to your installation. I will group these for you to decide how to best fit the style and activity level of your site.

Day 4 - Serve it up! (locally)
Before you go and load your site on a web server somewhere, you will want to have a local test environment where you can refine your site before making it public and test changes before you apply them to your public (production) web site. There are many packaged web servers that are easy to install and setup on your own computer. I have even gone so far as to set up a web server on my USB drive so I can take it with me everywhere! I use XAMPP for this, I believe WAMP and Uniform Server can do this, too.

I chose to use XAMPP, which I downloaded as a self-extracting executable. After extracting the XAMPP files to a different folder on my drive (not my XOOPS folder), I followed their instructions for finishing the setup of my web server. When you go to the XAMPP home page and select your operating system (Linux, Windows, Mac OS X, or Solaris), the page has links to installation steps and FAQs, as well as download links to the latest version.

Spend some time getting familiar with starting and stopping your web server and how to access and control the MySQL databases (usually through phpMyAdmin in your browser). Also, start your browser and try to open the default pages that come with the server to be sure it is running properly. If the pages display - congratulations! You have just launched your first web site.

After you have completed the setup of your web server, use their documentation to determine which folder will hold your new web site (your 'document root'). In XAMPP, there is an /htdocs folder, just like there is in the files you extracted for the XOOPS core. So, here we go - copy everything in your Xoops' /htdocs folder (not the folder itself) to your web server's document root. If you end up with something like /XAMPP/htdocs/htdocs, you didn't get it right. Undo that copy, reread this paragraph and try again.

Once you have your XOOPS files copied to your new server, resist the urge to immediately move on to installing Xoops! Go back to the XOOPS folder you started with and open the /docs folder. Open the install.html file there to review the installation process for XOOPS and some of the information you will need about your web server to continue successfully.

--- More Information ---
What is a web server?
Xoops Standalone Server (XSAS)
Web Server Requirements
XAMPP web server
Uniform Server
General Terms and Definitions

Many of these references were found by searching the XOOPS site, using both the XOOPS Search function and Google. In fact, most of what will be in this series has already been answered here at Xoops.org.

Day 5 - Almost Live!

So, if you followed instructions, you have not attempted to install your new XOOPS site locally. Now we are ready to make the big move.

Start your local server (Apache/MySQL - XAMPP in my case) and open your browser. Type http://localhost/ in your address bar and Go! You should get the first page of the XOOPS installation wizard. The screens should be familiar - they are the same ones you see when you looked at the install.html file in the /docs folder in your XOOPS installation package.

Before you move on to the next steps, be sure you have ready the database host (localhost for most, including XAMPP), the db username (root for XAMPP) and the db password (leave blank for XAMPP). If you have a web host already picked out, it will be worthwhile to determine these values for your hosting account. The database user settings for XAMPP and most other local servers will allow you to create your database as part of the installation. A lot of hosting packages require you to create the database through their cPanel or other administrative interface first. Just so you are prepared when you go online.

Click through the screens until you get to the general configuration screen (the 4th screen). Here is where the information above is entered. The installation script will do its best to guess, but make sure it is correct. For the database name, make one up that is different than the default - it's a bit more secure that way. My web host has a specific naming convention that includes part of the domain name, so I create a db consistent with that. Also, change the default table prefix! This is another security measure that adds some protection from malicious surfers. The physical path and url should be good, for now.

Complete the installation process, and if you've carefully followed the steps, you should get green lights all the way through. The last bit of information you will need to enter will be the user name, password and email address for the web site administrator. You can change it later, if you would like, but be sure to remember what you entered here!

Now that XOOPS is installed on your local computer, click on the link on the last page of the installation wizard to go to your new home page. It will be pretty blank, because you haven't added anything, yet. But, that will come. Enter your admin username and password to log in. Still not much more, but you will get the User Menu. I'd go ahead and click on Edit Profile and fill in any additional information that you would like to share about yourself - at least add a signature.

After that, we'll be heading the Administration Menu for a look around there. Stop here and go look through the XOOPS for Dummies site - click on Preferences in the menu on the left. Also look at the XOOPS Operation Guide. These both just go down the system menu, which is not the best order, in my opinion. Get familiar with the options in the preferences section and we'll go over them next time.

--- More Information ---
Xoops Installation Guide - provides more information about each of the screens and what is happening at each step. This was written in 2004, but most of the information is still relevant
Xoops for Dummies provides a lot of good basic information, even if it is a bit outdated.
Xoops Operations Guide
Installation Tutorial (Flash) by JSeymour

Day 6 - Your First Login

Once you login with your administrator username and password, you'll be able to see the User Menu and the various options in it. Since you have administrative rights, you will see a link to the Administration Menu. Go ahead and click on it. The next screen you'll see will let you know this is the first time you have accessed the administration area and a button to proceed. Most people move on and end up in the Admin area. Some get stuck in a loop and never seem to get to the Admin area. There is a FAQ that addresses the Endless Admin Login Loop, and also a forum topic.

Some of the resources mentioned previously are also excellent sources of information for beginning to administer your site. I'll go through in the order that makes the most sense to me.

Start by hovering over the System Admin icon on the right side of the page. You should notice there is a popup menu available that presents several options. You will also get an index of those options by clicking on the icon. Either click on Preferences in the popup menu, or click on the System icon, then Preferences. Make note of the other options, but leave them until later.

There are several additional options available under Preferences - click on General Settings first. What you will see next is a list of all the options you can set for your site. Most are pretty self-explanatory and others have additional information about themselves.

Here are a few important settings to look more closely at -

Your Site Name and Slogan get used in many themes to set the titles of pages and info at the top of every page. It will also get included in search engine results once you go online and the search engines start to 'crawl' your pages.

The server timezone and default timezone settings control how times get registered on your posts (articles, forums, calendar entries). You'll need to know where your actual server is located to get this right. Nothing major to worry about at the moment.

You don't have any modules installed, yet, so the option for your start page will be set to none.

Your default theme will determine what style your site will have when people first visit. XOOPS comes with 3 themes to choose from and you can download hundreds of others or create your own.

Going farther down the page, you will find the setting for Debug mode. When you are experiencing trouble, you will be urged to turn debug mode on and report the information displayed.

You can also turn your site off while you are changing some functionality or debugging a problem, and while it is off only the specified groups will be able to log in and access it pages. The others will see a page displaying the message you provide.

After you have set the General Options, click on the Go! button at the bottom of the page to save your options. If you have changed your site name and slogan, you can click on the Home link in the upper right corner and go back to the user side of your site and see those changes.

Back in the Administration area, go to Preferences - Meta Tags and Footer. Here you will find the settings for some non-visible portions of your site. These are visible to search engines and they are of some value. The option most people try to change is what displays at the bottom of every page, which is the Footer option at the very bottom of the page. Some themes do not use this information and you will not see any changes on your site until you change to another theme. The default theme with XOOPS 2.0.16 has a set footer and will not display this.

My next stop in the list of preferences is the Word Censoring Options. XOOPS will replace any words in the list you provide here with the text you place in the last option. There are some default settings here you can just accept, or create your own list and substitution value, or turn it off completely. It is up to you.

The last option we will look at is the Search options - it is pretty simple: do you want it activated and what is the minimum number of characters to use for searching?

The last 2 options - User Info Settings and Mail Setup require some additional attention, so we'll cover those in another entry.

--- More Information ---
Xoops for Dummies
Xoops Operations Guide

Day 7 - You Make the Rules

Running your web site on XOOPS gives you the flexibility to edit and maintain your content from any web browser, to provide custom content for different user groups, and to have interaction with your user community. This is both one of the biggest attractions of the web, and also (can be) one of the biggest challenges of maintaining a site. Having some clear rules and guidelines for users from the beginning helps a great deal.

We still need to complete our configuration of the System Preferences, specifically the User Info Settings and Mail Setup. Let's go to the User Info Settings next.

First, decide whether you will allow new users to sign up for your site. If you plan on having a pretty static site, perhaps providing logins isn't going to be necessary. Maybe you want to create logins yourself. But, if you've gotten this far in setting up a Xoops-based site, you will be accepting new registrations.

Next option - username minimum length and minimum password length. Best practice here - accept the default for username, but increase the minimum password length to at least 6 characters, preferably more.

Skip the next few options and go down to the strictness for username filtering - Strict is the default and will work best for most cases. Then a few more down is the username 'blacklist'. Enter a list of names you will NOT allow as usernames on your site. If you don't know what REGEX is, don't worry, it is just a method of expressing patterns instead of exact matches. The same goes for the email restrictions.

Now go back up the page to the notification and activation options. You will have to decide how involved you want to be with the whole registration process. Once people register, their accounts need to be activated.

Automatic activation is the simplest - as soon as they submit their registration their account is activated. You could get a lot of automated (spam) registrations with this option, so it is not recommended without a lot of thought to how the rest of your site is controlled.

User activation requires minimum attention on your part because new users will receive an email with a link to activate their account. This at least verifies their email address before they can activate.

Activation by administrator gives you the ability to approve or question any registrations before they are activated. Especially important if you want more control over username selections, information and web site links entered in their profile.

Once you have selected your activation method, decide how you want to be notified when a user registers. Be aware that if you select notify when users register and administrator activation, you will receive 2 emails - one for the registration notice, and the activation email. Play with the options to see what works for you.

Avatars (kind of personal logos) are optional and there are some posts and instructions for adding avatars in bulk to your site. If you want to allow users to upload their own avatars, you can, but proceed with caution - the type of photo they upload may not be appropriate for your site's other visitors.

I will cover this more later, but you should start to give thought to how you will control access to your site and how you will group your users. This will be a powerful tool for smooth administration of your site.

Once you set up the Mail Options, you will be able to test a few registrations to see how your options will work for you.

--- More Information ---
There are other modules that extend the registration options and profile options (Formulize and Registration Codes is one option to consider.

The XOOPS Admin Interface FAQ Category has lots of good topics about this area.

Xoops for Dummies - Preferences also has some great info about setting up your preferences

The XOOPS Operation Guide has a section on preferences (chapter 2, section 12)

Day 8 - You've Got Mail!

I haven't mentioned this yet, but there is a book about building XOOPS web sites See the block and link at the left --> (and it is not my book, someone else wrote it. Part of the proceeds goes to the XOOPS Foundation)

You've almost completed the basic administrative setup of your first XOOPS site. The only area left to configure in Preferences is Mail. I've left this for the end because it can vary for each server configuration (something your web host usually controls). There aren't a lot of options in the XOOPS configuration, but they cover a lot of variables for different servers.

The first 3 are not server dependent - the From name and From email address. Choose how your 'return address' should look on emails sent from your site. You may need to inform people about this address if they are not receiving emails from you - the address you select may be blocked by their spam filters and end up in the bit bucket (junk folder, recycle bin, whichever term you like). The third option is for private messages (PM). Which user should send system notifications?

There are 3 methods for sending mail - the php function mail (default), sendmail, or SMTP and SMTPAuth. SMTPAuth requires a host and a valid username and password for that host. Unless you have problems, stick with the default and you can leave the rest of the fields the way they are. When I run a local server for testing, I set the option to SMTP and provide the SMTP host for my ISP (usually something like smtp.myhost.com or mail.myhost.com) so I can test the email notifications before going live. I then modify the settings after going live, making sure everything works.

Now, save your settings and test out your email notifications - register as a new user! I always recommend having a site administrator (the user set up during installation) login different than your regular login. That way, when you need to make some configuration changes to your site, you need to deliberately login with your administrator login to make the changes - no accidental changes!

If all has gone well, you should get some email about the new user registering. Activate that user and be sure they (you) can log in.

So far, there haven't been a lot of decisions to make about your content or the concept of your site. The next big topic to address is the permissions for your site and how to set up user groups