Installation Guide:

Overview: The purpose of this task is to review the information in the Installation Guide https://www.drupal.org/documentation/install and see if it still applies to Drupal 8. , aside from the "Download" step (which is not available yet).

Details of this task

a) Download a Drupal 8.1.x release: https://www.drupal.org/project/drupal

Drupal 8 download

b) Aside from using (a) to find the Drupal download file, attempt to fFollow the installation instructions on https://www.drupal.org/documentation/install and install Drupal 8.

c) If you find any problems with the instructions (they are unclear or they don't work or something is different from what is described), add a comment to this issue explaining the problem, making sure to provide a link to the specific instruction page with the problem and describing any solutions you found, what you actually saw (screenshot could be useful), etc.

d) Also add a comment to this issue if you don't encounter any problems, so that we know that the guide has been reviewed.

Comments

chrischinchilla’s picture

chrischinchilla commented
Assigned: Unassigned » chrischinchilla
chrischinchilla’s picture

chrischinchilla commented

For utmost clarity at the moment I guess the instructions for D8 download should be a little different (not for ever though), i.e.

Instead of:

wget http://ftp.drupal.org/files/projects/drupal-x.x.tar.gz

a D8 release is currently

wget http://ftp.drupal.org/files/projects/drupal-x.x-x.tar.gz

etc… But this won't last for ever, so it may not be necessary.

chrischinchilla’s picture

chrischinchilla commented

At the "Create Database" step, it mentions that D8 can create a database if it is given enough permission (https://www.drupal.org/node/1845692). This is really useful, so I guess at some point it would be good to merge in this node into the main node, is now too soon?

I have rewritten for now, I would also suggest removing the mention of the change notice, it doesn't really add anything, but have left that for now.

chrischinchilla’s picture

chrischinchilla commented

So, at https://www.drupal.org/documentation/install/settings-file

It mentions duplicating the settings file, but according to the installer text (https://www.dropbox.com/s/9odezduukoi959e/2014-09-29%2010.34.02.jpg?dl=0) you also need to duplicate the 'services' file, so this needs to be changed.

Additionally, install.txt mentions that with correct permissions these files will be created automatically, which doesn't appear to be true.

chrischinchilla’s picture

chrischinchilla commented

With https://www.drupal.org/documentation/install/run-script

The instructions are in a different order for D8, it should be:

  1. Choose Language
  2. Choose Profile
  3. Verify Requirements
  4. Setup Database
  5. Install Site
  6. Configure Site

I am happy to make these edits, but now I'm thinking I should leave these major changes until given the go-ahead.

chrischinchilla’s picture

chrischinchilla commented

A general comment (which I don't think I've just helped) is that some pages do have D8 information and others don't, we should make a decisions one way or the other and start including or not…

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

Chris: THANKS for taking this on! It is definitely time to go ahead and edit the pages, if you are willing and able to do so!

chrischinchilla’s picture

chrischinchilla commented

In fact, in a lot of cases to due the database permissions and clean urls enabled by default, the D8 install documentation is actually a lot shorter, which is pretty ace.

chrischinchilla’s picture

chrischinchilla commented

I have updated docs to note that mod_rewrite (or equivalent) is needed for D8. However, the installation process makes no mention of this and you can theoretically end up with a broken site.

Whilst this is a concern relating to this task, there is a separate issue dealing with it - https://www.drupal.org/node/2094985 so let's see where that goes.

chrischinchilla’s picture

chrischinchilla commented

OK, largely done now. Happy to do some more in the future, as I image things might change in the near future :)

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

Thanks Chris!

Can you give a summary here: Are there additional things you think need to be updated in the installation guide that you didn't already fix? And are there additional things in the install guide that still need to be reviewed?

If so, make a list.

If not, mark this issue as Fixed.

Thanks!

batigolix’s picture

batigolix
Primary language Dutch
Location Utrecht
commented
Issue tags: +Documentation, +sprint
kellyo’s picture

kellyo commented

I'm going to go take a pass through the installation guide too, and see if I can find anything additional that needs reviewing.

kellyo’s picture

kellyo commented

Status Report

So, I went and grabbed the beta version of D8 (drupal-8.0.0-beta1) and ran through Steps 1-4 of the installation guide. Here were my findings/changes for each area:

Step 1: Download and extract Drupal

  1. A technical note, that I wasn't sure if I should probe further: At first, I downloaded the tar.gz file using the curl command. It downloaded just fine, but when I tried to extract it from the command line, I got an error:
    tar: Unrecognized archive format
tar: Error exit delayed from previous errors.

    (It wouldn't extract from Finder, either.)
    But when I went and downloaded the file directly from the project page, it all worked fine.

  2. There's a comment (from BigJonMX) on this page that expresses confusion about why we move the htaccess and gitignore files separately, and I ran into the same question. Moving the whole directory up does seem like it should already include both files, so I wasn't sure why we were calling them out specifically. If there's a specific reason, I'd like to explain what it is, at the beginning of the step. If not, we should probably cut these steps? (If, however, it's a thing we needed to do for D7 but we don't for D8, perhaps we should break this page into D7 and D8 sections like we do with the Step 4 page.

Step 2: Create the Database

This page worked for me, overall. The only thing I changed was updating the TOC to fix a broken link and add links to the specific direct creation options below.

Step 3: Create the settings.php file

This page, I had a little more in-depth editing I wanted to do, but I had a couple of questions I wanted to ask before I just jumped in:

  1. What does creating the settings.php file--and changing the permissions on it--do? I think that's the big thing I'm missing here. We're good, later on, at explaining that it's important to change the permissions back for security reasons, but we're less clear, here, about why it's important to create the file in the first place. If someone can tell me what this step does, I'll put a little explanation of it at the top of the page.
  2. For D8, this step now also includes the services.yml file. I'd like to go in and incorporate that into main step-by-step copy more clearly, but I wasn't sure if we were ready to go ahead and make the D8 process the default here or not. If not, perhaps we should divide up the content here according to D7/D8 etc. like we do later on?
  3. There's a note in here about D7 installs that's a little confusing: Note: With Drupal 7.x, on some types of shared/local hosting, if PHP and Apache are run by the same user, Drupal will attempt to execute the first three steps for you. If you get errors referring to the "Settings file" during installation, you can perform these steps manually. Aside from a couple of wording things I'd change for clarity, do we know if this is still true for D8?

Step 4: Run the installation script

This all worked just fine. The only change I made here was to include a note about editing the services.yml permissions at the same time you're editing the settings.php permissions.

General Question

Several of these pages have several tiers of child pages that offer more detailed advice specific to operating systems and whatnot. I was wondering if there's another way we could handle these pages that would keep them from showing up in the linear flow from one step to the next?

e.g. From Step 2: Create the Database, it'd be great if we could have the next link at the bottom go to Step 3: Create the settings.php file instead of the Create MySQL database with GoDaddy page. Is there a way we can roll these additional resources in or link to them somewhere else? (No is a totally legit answer here, I just figured I'd ask.)

batigolix’s picture

batigolix
Primary language Dutch
Location Utrecht
commented
Assigned: chrischinchilla » Unassigned
jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

@kellyo - thanks!

Some thoughts:

Step 1 - download
- It looks like the URL for the file is different in the wget vs. curl commands. They should be the same. Figure out which one is right, and fix the other? Both could also be wrong. It should be the same URL as on the Drupal project page.
- The reason for the mv command needing .htaccess and .gitignore separately is that * (at least in Linux) does not match file names that begin with . -- so that is correct. I do not think it needs to be explained -- standard behavior for the mv command.

Step 3 - settings file
1. While Drupal is being installed, Drupal needs to make changes to the settings.php file (puts in your database entries etc.). So the file needs to be writeable during install, and then should be changed back to read-only after install. And I think that Drupal doesn't create the file if it's missing (it may for some versions but I think not all).

2. We need to mention the services file... just say "For Drupal 8 you will also need to...". Even after Drupal 8 comes out, we would still want to make it clear what is Drupal 7 and what is Drupal 8, and support both.

3. I do not believe that Drupal 8 will do these steps for you but you can test to be sure.

General Question
- That's a problem with the Book module... which is lame. I think it's best to leave the structure as it is. I personally find the Book module's "previous/next" to be pretty much useless and I just always use the sidebar to navigate. Not much we can do about it.

hansfn’s picture

hansfn commented

Step 1 - download
- It looks like the URL for the file is different in the wget vs. curl commands. They should be the same. Figure out which one is right, and fix the other? Both could also be wrong. It should be the same URL as on the Drupal project page

I have fixed this - using the same correct URL for both wget and curl.

- The reason for the mv command needing .htaccess and .gitignore separately is that * (at least in Linux) does not match file names that begin with . -- so that is correct. I do not think it needs to be explained -- standard behavior for the mv command.

I agree.

I have improved the text for Drush - making it clearer: Drush is best, but has a learning curve.

I have two questions:

  1. How do we make step 1 correct for Drupal 8 in the simplest way. The biggest problem is that Drupal 8 has semantic versioning - drupal-x.x.tar.gz is replaced with drupal-x.y.z.tar.gz

    2. Could we start the page by saying that "We will use drupal-version.tar.gz which is drupal-x.y.z.tar.gz for Drupal 8 and drupal-x.y.tar.gz for Drupal 6 and 7." and on the rest of the page use "drupal-version.tar.gz"?

  2. The current instructions are for people with shell / SSH access to their server. I think it's more common to only have (S)FTP access. You download the files on your Windows machine, unpack and the upload the files to your server. How do we fix this? Do we need t create subpages or will it be OK to add more content to the current step 1? I suggest moving the current instructions to a sub page "Download and extraction if you have shell / SSH access" and add the "standard" procedure to the current page
jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

Thanks!

Here are my thoughts on the two questions in #21:

1. "drupal-x.y.tar.gz" -- So in practice, they might be downloading drupal-8.0.0-beta1.tar.gz or drupal-7.33.tar.gz... but looking at the Install Guide step 1 page, I really think it's clear enough as it is now. It is saying:

Replace the "http://drupal.org/files/projects/drupal-x.x.tar.gz" string in the commands with the link for the version you will be installing.
...
Type the following command (replacing "x.x" with your downloaded version's number):

Really, let's just leave this as it is. I really doubt anyone would get that confused, since we tell them where to go to find the links.

2. How about if we do this: At the top of the Step 1: Download page, add a note saying something like

As you learn more about Drupal, you'll probably find that you'll want to have "shell" (ssh) access to the server where you are installing Drupal. Most Drupal experts consider this essential, and the instructions on this page assume you have shell access. But if you do not have shell access, you can still install Drupal; see (make a link to a sub-page with these instructions).

And then make a child page with FTP instructions. The thing is, I think we do want to encourage people to start using the shell -- lots of stuff is eventually easier if you have shell access. OK?

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

Note on current status:

- Comment #18 needs to be addressed; see #20 for suggestions
- Comment #21 needs to be addressed; suggested resolution in #22.

ifrik’s picture

ifrik
she/her
commented

I've edited the Download and Extract page https://www.drupal.org/documentation/install/download, with the suggestions from here.
I've added a short list to explain that you can either use shell individual shell commands, drush or FTP, and then moved the bit about Drush under its own heading.
At this stage, a child page about how to install Drupal with drush is probably more relevant than, an explanation for FTP.

ifrik’s picture

ifrik
she/her
commented

Drupal 8 now has 6 hidden files that all need to be moved manually.
I've therefore added a bit about how to extract this directly into the right location, following the comment #1 on https://www.drupal.org/documentation/install/download
Is it okay to unpublish that comment, now that it has been taken up?

Or should we just get rid of the whole explanation of moving the files and only explain how to un-tar the tar ball into the correct directory straight away?

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

This looks good... but maybe we should use a nesting of H3 and H4 for these sections, and I didn't see any explanation of how to do it with FTP? I think we probably should add some?

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

Actually I've edited the page to do this.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

I deleted the comment. We normally delete comments that have been included in the page.

ifrik’s picture

ifrik
she/her
commented

About the Create the settings.php file https://www.drupal.org/documentation/install/settings-file

Should we rename that to "Create settings and service files? That way it covers D8 properly as well.

About the permissions:
Why is the command for the settings.php file "chmod a+w" and not "chmod g+w"? That corresponds with "chmod 664" and safer in case somebody forgets to restrict the settings again.
The same goes for changing the permissions for the default directory.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

Rename sounds like a good idea.

I don't think chmod 664 or g+w will work for most people. For instance on my local machine I have to use "a" or 666 because I am not a member of the same group as the web user.

ifrik’s picture

ifrik
she/her
commented

I've renamed the https://www.drupal.org/documentation/install/settings-file to Create settings.php and service.yml files.

I've also replaced the list by h2 and h3 headings because with all the options it was looking a bit messy.

ifrik’s picture

ifrik
she/her
commented

About the installation script https://www.drupal.org/documentation/install/run-script
How about moving the installation for Drupal 6 to a seperate page, concentrate the main page on D7 and D8?

batigolix’s picture

batigolix
Primary language Dutch
Location Utrecht
commented

I simplified the drush section a bit and added the command to do that

batigolix’s picture

batigolix
Primary language Dutch
Location Utrecht
commented

also reviewed / lightly touched the FTP section

ifrik’s picture

ifrik
she/her
commented

I noticed that the error messages for "requirement problems" refer to a list of handbook pages, for trouble-shooting, but not to the installation guide.

Wouldn't it be better to refer to the installation guide, and add the links to relevant troubleshooting pages to the guide?

And since we use "online documentation" instead of "handbook pages" I suppose that should be changed as well.

ifrik’s picture

ifrik
she/her
commented

I might be going down a rabit hole here.... how about first updating the INSTALL.txt file, to include the proper command to extract the tar ball into the right directory, to mention drush etc, and then put that onto the web pages, and add (links to) addititional trouble shooting or more info?

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

RE #32, if D6 is quite different, I agree: make the main page about D7/8 and move D6 to a sub-page (with a link).

RE #35/#36 - if the D8 installation is referring to the handbook or the INSTALL.txt is outdated, then we should file separate D8 core issues (probably one for the error messages and a separate one for install.txt) and get that fixed. This would be a great time to do that.

ifrik’s picture

ifrik
she/her
commented

I've made two new issues:

Poornima3’s picture

Poornima3 commented
Issue summary: View changes
tadityar’s picture

tadityar commented

Screenshots are outdated in Run-script section of D8. Can I update the screenshots?

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

@tadityar - Sure, please do! Any page in the Community Documentation section where you see an Edit button, you are encouraged to improve. :)

jay-dee-ess’s picture

jay-dee-ess commented
Issue summary: View changes

removed reference to beta

no_angel’s picture

no_angel commented
Issue summary: View changes

- Amsterdam2014
- sprint

drupal 8 download link (now available).

@jhodgdon,

I'm a bit confused on where exactly someone would be installing drupal following the installation instructions?

Is the point to provide details on installing drupal 8 on local environment as well as on a web server thru a hosting provider?

no_angel’s picture

no_angel commented

- sprint, Amsterdam2014

kumarnraj93’s picture

kumarnraj93 commented
Title: Review installation guide for Drupal 8 » module installation.
Assigned: Unassigned » kumarnraj93
Category: Task » Support request

i want to create a menu like atm display in drupal 8 in local site. please reply me.

hansfn’s picture

hansfn commented
Title: module installation. » Review installation guide for Drupal 8
Assigned: kumarnraj93 » Unassigned
Category: Support request » Task

Reverting changes made by kumarnraj93.

@kumarnraj93: Please use the forums or Drupal Answers for support question (and never hijack an issue like you just did).

xaiwant’s picture

xaiwant commented
Status: Active » Needs review

..

ifrik’s picture

ifrik
she/her
commented
Issue tags: +Usability
Related issues: +#2695411: [meta] Fix text based usability issues
doubutsurb’s picture

doubutsurb commented

Image415 and I are checking this at NOLA Dcon. More in a bit... :-)

image415’s picture

image415 commented

a

image415’s picture

image415 commented

doubutsurb and I are reviewing this at Drupalcon Sprint

doubutsurb’s picture

doubutsurb commented

Image415 and I feel a "deprecated" or "no longer supported" should be added to the "Drupal 6" install link. Editing the page to that effect.

doubutsurb’s picture

doubutsurb commented

Added a "Note: Drupal 6 has reached end of life and is no longer supported. You are highly encouraged to instally D7 or above." note to the D6 install section, to clarify that this version shouldn't really be installed anymore.

sparklingrobots’s picture

sparklingrobots
she/they
Primary language English
Location United States
commented

Thank you image415 and doubutserb for your work on this at the New Orleans Sprint.

Next steps for this issue could be:

  1. An updated issue summary
  2. A list of remaining tasks that will allow us to close this issue
ifrik’s picture

ifrik
she/her
commented
Issue tags: +DevDaysMilan

It would be great if we could get this done at DevDays in Milan.

tea.time’s picture

tea.time commented

Hi,

I'd like to suggest an addition to the Database step of the docs: it seems that the database collation must be utf8mb4_general_ci for Drupal 8. I can't find official docs stating this requirement, but did find #1314214: MySQL driver does not support full UTF-8 (emojis, asian symbols, mathematical symbols) and #2529188: Provide better error handling for MySQL client and server utf8mb4 incompatibility which strongly imply so -- hence I'm commenting here instead of editing the documentation page directly.

I only happened to discover this because today I created an empty database for a local D8 install, setting the collation to utf8_general_ci (as I'd done before on all D7 databases), then happily imported a dump of another install of the site, only to get a PDOException: SQLSTATE[42000]: Syntax error or access violation: 1253 COLLATION 'utf8_general_ci' is not valid for CHARACTER SET 'utf8mb4'... Once I changed the database collation to utf8mb4_general_ci and specified that same collation in settings.php, all was well. :)

vpanicke’s picture

vpanicke commented
Issue summary: View changes
vpanicke’s picture

vpanicke commented
Issue summary: View changes
hansfn’s picture

hansfn commented
Status: Needs review » Closed (outdated)

Since we both have a User Guide explaining the installation and a separate installation guide for Drupal 8 at https://www.drupal.org/docs/8/install I think this issue isn't relevant anymore.

I'm closing this as outdated. Please open new issues (if needed) to improve the existing docs.