Quick Start Guide Version 3.0. Updated September 20, 2013

Transcription

1 Quick Start Guide Version 3.0 Updated September 20, 2013

2 Contents 1. Welcome...2 Overview...2 How Gallery Server Pro works...2 Requirements...3 Product key...3 SQL Server support...3 Known issues Installing/Upgrading Gallery Server Pro...4 New Installation...4 Upgrading from 3.0.X...7 Upgrading from Upgrading from 2.5 and earlier...8 Gallery Server Pro Binary Pack Switching from SQL Server to SQL CE...9 Overview HOW-TO: Integrate Gallery Server Pro with Active Directory Overview Instructions HOW-TO: Upgrade an AD-enabled gallery from Welcome Gallery Server Pro is a web application for sharing photos, video, audio, documents and other files. It s like having your own personal YouTube or Flickr site. It is intended for users who want to share large collections of media objects on their own web site while maintaining a high degree of control. Overview This guide is a temporary document to help you get up and running. Once the Administrator's Guide is fully updated for 3.0, this document will be discontinued. Even though the Admin Guide is for the older version, many of the concepts and patterns remain the same, so you may wish to refer to it. How Gallery Server Pro works Gallery Server Pro is a web application you install on your web server or your web hosting company's server. Add your media library by synchronizing your directory containing photos, videos and other media objects with the Gallery Server Pro database. You can also ZIP your files and upload them. Gallery Server Pro 3.0 Quick Start Guide Page 2 of 21

3 Gallery Server Pro automatically creates a thumbnail image to represent each media object. If you upload a high resolution image, a bandwidth-friendly, compressed version is created. EXIF, IPTC and other types of metadata are extracted and stored in the database. Media object files are stored on the local hard drive or a UNC-accessible location such as a NAS device or network share. Metadata about these files, such as width, height, caption, etc. are stored in the database. When web users browse your albums and media objects, Gallery Server Pro queries the database for the necessary information, and dynamically renders a custom web page. If watermarking is enabled, the watermark is applied to the image before it is sent. When the free Gallery Server Pro Binary Pack is installed, additional functionality such as video / audio encoding and thumbnail extraction from videos, TXT, PDF, EPS, and PSD (Photoshop) files becomes available. Requirements Server Requirements: Microsoft.NET Framework 4.5 or higher Internet Information Services (IIS) 7.0 or higher or a compatible web server Optional: SQL Server 2005 or higher, including the free Express versions. It does not have to be installed on your server, but it must be available on the network. Optional: SMTP server (required for functionality). Optional: Full trust. When the gallery is running under full trust, it automatically takes advantage of features available only in full trust, such as video and audio transcoding. Client Requirements: Any modern web browser (IE 5+, Netscape 6+, Firefox, Opera, Safari, Chrome) Product key Gallery Server Pro is fully functional for the first 30 days. At the end of the trial period, a watermark appears on each image and the Site Admin area becomes read-only. Enter a product key to restore full functionality. The product key determines whether the version converts to the free GPL, GPL Professional, or Enterprise edition. SQL Server support Your gallery can use either SQL CE or SQL Server during the 30-day trial. To continue using SQL Server beyond the trial, you must purchase the Enterprise edition. SQL Server is up to 20 times faster than SQL CE and is highly recommended for large galleries and for any site where high reliability and performance is critical. Gallery Server Pro 3.0 Quick Start Guide Page 3 of 21

4 If you want to switch to SQL CE so that you can use the free GPL edition, follow the directions in the section Switching from SQL Server to SQL CE. Known issues None 2. Installing/Upgrading Gallery Server Pro New Installation Installation has been simplified when compared to 2.6 and earlier. Follow these steps: 1. Download the install/upgrade version of the stand-alone version of Gallery Server Pro from the download page. 2. Extract the zip file to a directory. Configure the directory to run as an application in IIS under.net 4.5. Make sure the IIS process identity has modify permissions to the App_Data and gs\mediaobjects directory. NOTE: IIS will report the application pool is running under 4.0 even when 4.5 is installed. 3. SQL Server only: To use SQL Server, open web.config and comment out the SQL CE connection string named GalleryDb. Uncomment the connection string for SQL Server and modify it to use your credentials. Be sure it is named GalleryDb. If the specified database does not exist, the gallery will attempt to create it when the app starts. Be sure the credentials have permission to carry out this task or create the database manually first. 4. Open default.aspx in a web browser. The database will automatically be configured and seeded with default data. This step may take a minute or two, so be patient. The screen will look like this: Gallery Server Pro 3.0 Quick Start Guide Page 4 of 21

5 5. Click the link to create an admin account. Enter a username and password and you are all set! Gallery Server Pro 3.0 Quick Start Guide Page 5 of 21

6 Gallery Server Pro 3.0 Quick Start Guide Page 6 of 21

7 Upgrading from 3.0.X 1. Download the upgrade version of Gallery Server Pro. The file is named GalleryServerPro_V3_0_2_Upgrade.zip. NOTE: The upgrade version is exactly the same as the install version except it doesn t have web.config or the App_data directory. 2. Extract the contents over your existing application. 3. Open the gallery in the browser. You are now running the new version! NOTE: You may get the error "Error: Cannot read property 'Id' of undefined." or "Error: undefined is not a function." You just need to tell your browser to download the new JavaScript files. Usually hitting F5 once or twice will do the trick). Upgrading from 2.6 Version 3.0 requires.net 4.5, so be sure your server has this version installed before upgrading. Gallery Server Pro 3.0 Quick Start Guide Page 7 of 21

8 Below are step by step directions for upgrading your version of Gallery Server Pro. Note: If you get an error, temporarily make these two changes to cause detailed messages to be rendered in the browser: (1) Set customerrors= Off in web.config (2) Set debug= true in web.config 1. Make a backup of your database, web files, and media files. You ll only need them if the upgrade fails and you need to revert to In your 2.6 gallery, go to the backup/restore page and create a backup file of your user accounts and gallery data. 3. Delete the gallery web files from your server. DO NOT delete your media files (the ones stored in gs\mediaobjects by default). 4. Download the install/upgrade version of the stand-alone version of Gallery Server Pro from the download page. Extract the contents to your web server, in the same location you had As with 2.6, the IIS account needs modify permission to the App_Data and gs\mediaobjects directories. Do this using Windows Explorer or your web host control panel. 6. If using SQL Server, open web.config and update the connectionstrings section to use the SqlClient provider instead of SQL CE (that is, comment out the SQL CE connection string and uncomment the SQL Server one.) Then update the SQL Server connection string to point to your gallery database. The credentials you specify must have permission to create database objects. Note that 3.0 uses a completely different naming scheme, so the 3.0 tables can exist alongside your 2.6 ones until you get a chance to manually delete the 2.6 ones (if you want to). For example, the table gs_album from 2.6 is named Gsp.Album in 3.0 (note the use of a new Gsp schema). 7. Open default.aspx in a browser. The gallery will detect that no data structure exists for the connection string named GalleryDb and automatically create it. (For you techies it s using Code First Migrations for this part.) 8. A default page will load with a message allowing you to create an admin account. Go ahead and create one. This account will be replaced during the restore operation, so don t worry about saving the password. 9. Now you should be able to go to the backup/restore page in your 3.0 gallery. Click the restore tab and upload the backup file you created in step 2 above. Then restore it. 10. The restore operation detects the file is from 2.6 and upgrades the schema as it imports it into the new tables it created in step 7. For large galleries this can take a few minutes, especially if you are using SQL CE. 11. Once complete, review the settings on the various admin pages to verify everything looks the way you want it. NOTE: The list of enabled file types reverts to only jpg and jpeg files. After the upgrade, go to the Media Object Types page to re-enable the desired file types. Upgrading from 2.5 and earlier You can upgrade from 2.5 and earlier, following a two-step process: Gallery Server Pro 3.0 Quick Start Guide Page 8 of 21

9 1. Upgrade to Upgrade from to 3.0. To perform the migration to 2.6.1, go to the Gallery Server Pro Release History and download the upgrade package. Then follow the upgrade instructions in the Administrator s Guide, also found on this page. Once your site is running 2.6.1, follow the directions in the Upgrading from 2.6 section. Gallery Server Pro Binary Pack Gallery Server Pro provides advanced media capabilities such as video/audio encoding and thumbnail extraction from videos and a variety of document types (text files, PDF, EPS, and PSD (Photoshop) files). These features require the installation of the Gallery Server Pro Binary Pack, which be downloaded on the download page. The Binary Pack contains three open source components: ImageMagick Creates thumbnail images from EPS, PSD, TXT, and PDF files. It requires GhostScript to be able to create images from EPS and PDF files. How to install: Copy convert.exe to the bin directory. GhostScript GhostScript knows about the internal format of EPS and PDF files. How to install: Execute the setup program on the web server. FFmpeg Creates web-optimized videos and thumbnail images from video files. How to install: Copy ffmpeg.exe to the bin directory. Installing these utilities is optional. If they are not present, encoding is not possible and Gallery Server Pro falls back to the default technique of using a generic image for the thumbnail. NOTE: My experience has demonstrated that you must install the 32-bit version of GhostScript, even when installing on a 64-bit server. 3. Switching from SQL Server to SQL CE Overview SQL Server storage is supported only in the Enterprise edition. SQL Server is up to 20 times faster than SQL CE and is highly recommended for large galleries and for any site where high reliability and performance is important. If you want to switch to SQL CE so that you can use the free GPL edition, follow these directions. Gallery Server Pro 3.0 Quick Start Guide Page 9 of 21

10 You do not need to follow these steps if you are upgrading from 2.6 and want to switch to SQL CE during this process. Instead, just follow the upgrade instructions and configure the 3.0 gallery to use SQL CE. Your backup file made from SQL Server in 2.6 can be restored to a SQL CE-based gallery. NOTE: These same directions can be used to switch in the other direction, from SQL CE to SQL Server. Just change the connection strings from SQL CE to SQL Server in step Make a backup of your database, web files, and media files. You ll only need them if the conversion fails. 2. Go to the backup/restore page and create a backup file of your user accounts and gallery data. 3. Open web.config and update the connectionstrings section to use the SqlServerCe provider instead of SQL Server (that is, comment out the SQL Server connection string and uncomment the SQL CE one.) It should look like this: <connectionstrings> <clear /> <add name="gallerydb" providername="system.data.sqlserverce.4.0" connectionstring="data source= DataDirectory \GalleryData.sdf" /> <!--<add name="gallerydb" providername="system.data.sqlclient" connectionstring="server=(local);uid=;pwd=;trusted_connection=yes;database=gallerydb;application Name=Gallery Server Pro;MultipleActiveResultSets=True" />--> </connectionstrings> 4. Add an empty text file named install.txt to the App_Data directory. 5. Open default.aspx in a web browser. Gallery Server Pro will detect the new connection string and automatically create a database file named GalleryData.sdf in the App_Data directory with a default set of data. The screen will look like this: Gallery Server Pro 3.0 Quick Start Guide Page 10 of 21

11 6. Click the link to create an admin account. This account will be replaced in the next step, so don t worry about saving the password. NOTE: The link to create an admin account works only when install.txt is present in the App_Data directory. Once the account is created, Gallery Server Pro deletes the file. 7. Go to the backup/restore page. Click the restore tab and upload the backup file you created in step 2 above. Then restore it. 8. The data is now in SQL CE and your gallery should look the same as before. Sweet! Gallery Server Pro 3.0 Quick Start Guide Page 11 of 21

12 4. HOW-TO: Integrate Gallery Server Pro with Active Directory Overview You can configure Gallery Server Pro to use your existing accounts in Active Directory. This allows your users to log in with the same username and password they use to access the network, reducing account duplication and maintenance issues. Accounts can be added to roles just like with a regular installation. There is currently no support for Windows Groups. Instead, you create custom roles in Gallery Server Pro that are stored in the SQL Server database along with the rest of the gallery data. Users are added to one or more roles, giving them the desired access to the gallery items. Notes: You must use SQL Server for the role provider. IIS Manager allows one to add users to a role only when the role provider is trusted and added to the Global Assembly Cache (GAC). However, the SQL CE role provider cannot be added to the GAC because it is not strongly named. This prevents you from completing the step where you add a user to the System Administrator role with IIS Manager. You must use System.Data.SqlRoleProvider. Version 3 of Gallery Server Pro replaced System.Web.Security.SqlRoleProvider with System.Web.Providers.DefaultRoleProvider. However, this provider is incompatible with the AD membership provider, so you must switch back to System.Web.Security.SqlRoleProvider. The instructions will step you through this process. Gallery requires AD user update permission. Adding users to roles requires that the web application have update permission to Active Directory. There are two ways to do this (1) Specify a domain account in web.config that has user update permission (2) Run the IIS application pool under an account with user update permission. The second is more secure as it does not require a username and password to be specified in plain text. Note: It s a security risk to run the application with elevated permissions. Look for a future version to eliminate this requirement. Until then, I recommend running the app with elevated permission only long enough to configure the desired role membership for your users. Unable to add group to role. A common scenario is to add a group to a role. For example, you might want to add Domain Users to a role with read-only access and Domain Admins to the System Administrator role. Unfortunately, I have not been able to figure out how to configure the LDAP connection string so that it shows groups on the Manage Users page. If you know how to do this, please let me know. The basic process goes like this: 1. Start with an installed, working version of a gallery using SQL Server. 2. Install the data schema required by SqlMembershipProvider and SqlRoleProvider. 3. Modify web.config to use the new data schema. 4. Create an admin account that is stored in the new tables. Gallery Server Pro 3.0 Quick Start Guide Page 12 of 21

13 5. Change the membership provider to System.Web.Security.ActiveDirectoryMembershipProvider. 6. Use IIS Manager to assign one of your AD accounts to the gallery s System Administrator role. The instructions below provide detailed guidance for these steps. Instructions 1. If you haven t already done this, install Gallery Server Pro using SQL Server as the data store. Note: During installation you will specify an administrator account. Once Active Directory is integrated, you will no longer use this account. 2. Now you need to create the tables required by SqlRoleProvider (aspnet_users, aspnet_roles, etc). Run the aspnet_regsql.exe utility (by default it is at C:\Windows\Microsoft.NET\Framework\v ). The first screen looks like this: 3. Click Next and verify the option Configure SQL Server for application services is selected: Gallery Server Pro 3.0 Quick Start Guide Page 13 of 21

14 4. Enter the SQL Server credentials and choose the gallery database: 5. Click Next a couple times to complete the wizard. 6. Open the web.config file in the root of the gallery in a text editor. a. Add a connection string for AD to the connectionstrings section: <add name="adconnection" connectionstring="ldap:// /cn=users,dc=mydomain,dc=techinfosystems,dc=com"/> Note: The value is the IP address of the domain controller. You can also specify the Fully Qualified Domain Name (ex. mydomain.techinfosystems.com), the Relative Gallery Server Pro 3.0 Quick Start Guide Page 14 of 21

15 Distinguished Name (ex. godzilla if that is the name of your DC); or for more redundancy you can specify just the domain name (ex. mydomain). b. Replace the membership and rolemanager sections with the following. Be sure to update the connectionusername and connectionpassword with a domain account that has permission to edit users. <membership defaultprovider="sqlmembershipprovider"> <providers> <clear /> <add name="sqlmembershipprovider" connectionstringname="gallerydb" applicationname="gallery Server Pro" passwordformat="clear" minrequirednonalphanumericcharacters="0" minrequiredpasswordlength="2" maxinvalidpasswordattempts="50" enablepasswordreset="true" enablepasswordretrieval="true" passwordattemptwindow="10" requiresquestionandanswer="false" requiresunique ="false" type="system.web.security.sqlmembershipprovider" /> <add name="aspnetactivedirectorymembershipprovider" type="system.web.security.activedirectorymembershipprovider, System.Web,Version= ,Culture=neutral,PublicKeyToken=b03f5f7f11d50a3a" connectionstringname="adconnection" enablesearchmethods="true" attributemapusername="samaccountname" connectionusername="administrator" connectionpassword="thepassword" /> </providers> </membership> <rolemanager enabled="true" cacherolesincookie="true" cookieprotection="validation" defaultprovider="sqlroleprovider"> <providers> <clear /> <add name="sqlroleprovider" type="system.web.security.sqlroleprovider" connectionstringname="gallerydb" applicationname="gallery Server Pro" /> </providers> </rolemanager> SECURITY WARNING: Putting an AD account name and password in a plain text file is a security risk. I HIGHLY recommend you encrypt the web.config file. Here are two links where you can learn more: How To: Encrypt Configuration Sections in ASP.NET 2.0 Using DPAPI and Video: How Do I: Encrypt My Web.Config File? As an alternative, you can specify an account for the IIS application pool process identity that has the necessary AD permission. Why is this needed? There are two reasons: (1) The.NET Users applet we re going to use to assign the first user to the admin role requires it. (2) Changing a user s role membership in Gallery Server Pro requires it. However, we do not strictly need edit permission if all we are doing is adjusting a user s role membership, and I ve already thought of a way to get around this requirement. Look for a future version to improve this situation. 7. Use Windows Explorer to navigate to the App_Data directory of the gallery web application. Add an empty text file named install.txt. Note: This file is detected by Gallery Server Pro and will allow you to complete the next step. It will be automatically deleted. 8. Use your browser to navigate to (Change the URL as required for your installation, but be sure g=createaccount is the query string.) Note: If you get redirected back to the gallery home page and are sure install.txt is in the App_Data directory, try recycling the IIS application pool and trying again. Gallery Server Pro 3.0 Quick Start Guide Page 15 of 21

16 9. After accepting the license agreement, you will see the same account creation screen you used when you first installed the gallery. Enter a username and password and click Create account. Note: The purpose of this step is to create the System Administrator role in the aspnet_roles table (this is the table used by SqlRoleProvider). The original gallery installation created this role in the Roles table, which we are no longer using. The user account you create here will ultimately be abandoned once AD integration is complete. 10. View the gallery, then click the log out button. If you remain logged in, the cookie will cause an authentication error later when you switch to AD. 11. In web.config, change this line: <membership defaultprovider="sqlmembershipprovider"> To this: <membership defaultprovider="aspnetactivedirectorymembershipprovider"> 12. Add a domain user to the System Administrator role. We ll use the.net Users applet in IIS Manager to do this. Unfortunately, this applet does not work with.net 4 apps, so we have to trick it into thinking it s a.net 2.0 app. a. Open web.config again in a text editor. Change this line: <compilation debug="false" targetframework="4.5"/> to this: <compilation debug="false" /> b. In IIS Manager, modify the gallery web application to run under.net 2.0. You can do this by temporarily switching to a.net 2.0 application pool or changing the existing application pool to Gallery Server Pro 3.0 Quick Start Guide Page 16 of 21

17 run under.net 2.0. Here s how to do the first option: Select the web application in the left pane and select Basic Settings in the right Actions pane: 13. Click Select and choose an application pool that runs under.net 2.0: a. In IIS Manager, open the.net Users applet: Gallery Server Pro 3.0 Quick Start Guide Page 17 of 21

18 Note: If the applet is missing, refresh the screen with F5. If you still don t see it, verify the steps above. It won t show the applet when the requirements are not met. b. A list of Active Directory users appears. Choose one to be the gallery administrator. Right-click the name and choose Edit. c. Add the user to the System Administrator role and click OK. Gallery Server Pro 3.0 Quick Start Guide Page 18 of 21

19 Note: The form requires an address. If you need it to be empty, you ll have to use the Active Directory Users and Computers app to reset it after you add the role. d. Now that you have a user assigned as an admin in the gallery, you can revert the changes you made to force the app to run under.net 2.0: (a) Change the application pool back to.net 4.0 (b) Add targetframework= 4.5 back to web.config. Optional: You can also target the 4.0 version of the AD and role providers by changing the string Version= to Version= in the two places it appears in web.config. I don t know that this makes any practical difference but I always like to run the latest version when possible. 14. Finished! At this point you should be able to log in to your gallery using an AD account: If you are logged in with an account in the System Administrator role, you can go to the Manage Users page and see a list of all AD users and adjust role membership for them: Gallery Server Pro 3.0 Quick Start Guide Page 19 of 21

20 Note: If you get an error when viewing the gallery, it may be because of an authentication cookie left from the previous account. If the cookie was temporary, restarting the browser will delete it. If it was persistent (you clicked the stay signed in checkbox), you will have to explicitly delete the cookies from your browser. CAUTION: If the gallery is running under elevated permissions, any user in the System Administrator role can add, edit, and delete domain accounts. In most cases you do not want this behavior, so one option is to configure the users in the desired roles and then update web.config or the IIS application pool to revert back to the original permissions (e.g. remove the AD account name from web.config). If you subsequently need to adjust role membership in the gallery, temporarily increase the web application permissions, make the changes, and revert back. 5. HOW-TO: Upgrade an AD-enabled gallery from 2.6 Upgrading a 2.6 gallery that has been integrated into AD is a little tricky due to the way membership data is stored. Follow these steps for a successful upgrade. Gallery Server Pro 3.0 Quick Start Guide Page 20 of 21

21 1. Make a backup of your database, web files, and (optionally) your media files. You ll only need them if the upgrade fails and you need to revert to In your 2.6 gallery, go to the backup/restore page. Uncheck the option Export user accounts. Then create the backup file. 3. Delete the gallery web files from your server. DO NOT delete your media files (the ones stored in gs\mediaobjects by default). 4. Download the install/upgrade version of the stand-alone version of Gallery Server Pro from the download page. Extract the contents to your web server, in the same location you had Open web.config (in the root of the web application directory) and update the connectionstrings section to use the SqlClient provider instead of SQL CE (that is, comment out the SQL CE connection string and uncomment the SQL Server one.) Then update the SQL Server connection string to point to your gallery database. DO NOT SPECIFY ANY AD SETTINGS AT THIS TIME. 6. Open default.aspx in a browser. The gallery will detect that no 3.0 data structure exists and automatically create it. 7. The default page will load with a message allowing you to create an admin account. Go ahead and create one. This account will be replaced during the restore operation, so don t worry about saving the password. 8. Now go to the backup/restore page in your 3.0 gallery. Click the restore tab and upload the backup file you created in step 2 above. Then restore it. For large galleries this can take a few minutes. 9. WHEN THE RESTORE IS COMPLETE, DO NOT CLICK TO VIEW THE GALLERY. Instead, open web.config and add the AD connection string to the connectionstrings section and replace the membership and rolemanager sections with the ones from your old web.config file. 10. Now use your browser to load the gallery. The upgrade should be complete and you can log in with your AD account. Gallery Server Pro 3.0 Quick Start Guide Page 21 of 21