This is a set of sample files for the ocPortal application. These files could be used for designing an application package for ocPortal designed for the Web Application Gallery. The samples are annotated with comments throughout that explan specific issues encountered with the ocPortal application, as well as general commentary on the files themselves.
This application uses a number of SQL files for the install which are very specific to ocPortal. As a result these are not documented here. The user.sql script referenced in these samples is just a renamed version of the standard install.sql script from the other samples and the database notes that is used to create the database user.
There are two unfinished pieces of this application's install:
- There is a variable in the info.php file that is not being populated by the install. I'm not sure if the intent was to generate the value from PHP system variables, or to add another parameter to ask the user. The variable is $SITE_INFO['base_url'].
- There is a file called fixperms.bat in the root of the application which is used to set a bunch of ACLs. These should be moved into the manifest and parameters files for the reasons in the comments below.
A sample web.config file is included at the end. We recommend that all PHP applications have this base web.config file at the root of their applications.
Sample manifest.xml file
<MSDeploy.iisApp>
<!-- iisapp path identifies the subdirectory in the ZIP file which
contains all of the application files
-->
<iisApp path="ocportal" />
<!-- dbmysql path identifies the SQL script file that will be
executed for database setup. In this app's case, the script is
being used to create the database user for the application
-->
<!-- #ocportal - The original install.sql file from ocportal was too
big to be executed within the Web Deployment Tool's timeouts (15
seconds for a single SQL File). So, I broke the sql file into 4
files. In addition, I put our usual install.sql file which creates
the user in as 'user.sql'. This way the database user gets created
by the Web Deployment Tool, and will be ready when the user is
ready to load the site
-->
<dbmysql path="install1.sql" />
<dbmysql path="install2.sql" />
<dbmysql path="install3.sql" />
<dbmysql path="install4.sql" />
<dbmysql path="user.sql" />
<!-- alias is used to make a copy of a distribution file to a
location where it will be used. Note that when you specify the
Application name in the "to" attribute, you should specify the full
path using the value of iisapp above for the root. Alias doesn't
actually copy the file within the package. It creates an alias to
the original file using the new file's path and name. This alias
then gets copied to the file system as if it were a real file within
the package
-->
<alias from="info.php" to="ocportal\info.php" />
<!-- setAcl is used to set access permissions on a file or a folder.
The path specifies the object to apply the ACL to. The setAclAccess
attribute specifies the permissions. setAclUser is used to identify
the user that the ACL is for. The special name
"anonymousAuthenticationUser" is used to represent a generic id that
will allow the PHP process to access the file with the set
permissions. The default setting is that the object in the ACL path
is a directory. If it is a file, include the attribute
"setAclResourceType" and set it's value to "file".
If no ACL is set on a file or directory, the ACL defaults to "Read."
The ACLs are specific, so granting Write access does not necessarily
grant Read access. If you must write to a file or directory, you
should add "Read,Write". If you need to be able to enumerate the
files in a directory, you should add "ListDirectory". Note that
Write access does not grant Modify access. If you will need to
change files once they are written to disk, you will need to
explicitly set "Modify" access. There are some permissions that are
combinations of other permissions. For example, "Modify" includes
"Read", "Write", "Execute", and "Delete".
-->
<!-- #ocportal - There is a file called fixperms.bat in the root of
the ocportal distribution. This file uses the 'cacls.exe' command
to set the permissions on 137 files or directories within the
ocportal application tree. I would strongly recommend removing that
file and replacing it with setAcls here and in the parameters.xml
file for the following reasons:
1. cacls.exe has been replaced by icacls.exe and won't work in all
environments.
2. The script sets the user to: NT AUTHORITY\NETWORK. This is only
apporpriate for versions of IIS prior to IIS7. The Web Deployment
Tool will always set the ACL for the proper user based on the OS and
version of IIS.
3. The script assigns "Full Access" for all of the ACLs. Cacls did
not have the granularity available in icacls and in the Web
Deployment Tool. In general, we recommend that developers apply
"Modify" permissions for places where the application needs to be
able to read, write and execute files. This is the equivalent of a
'7' in linux permission modes.
4. The Web Deployment Tool has no mechanism to execute this script
as part of the installation. When first connecting to ocPortal, if
the script hasn't been run, the user is presented with an
error message which doesn't give a novice user sufficient
information to figure out how to run fixperms.bat. The
general experience that we are seeking for the Application
Gallery is that a user can select an application to install,
answer the questions needed by the Web Deployment Tool, and
then be able to view the site, or at least the next step in
the setup process straight from their browser.
-->
<setAcl
path="ocportal/uploads"
setAclAccess="Modify"
setAclUser="anonymousAuthenticationUser"
/>
</MSDeploy.iisApp>
Sample parameters.xml file
<parameters>
<!-- iisapp - This identities a parameter as the application path to
install the app. The defaultValue will be displayed by most
installers. The defaultValue should be set to something like
"Default Web Site/application1" where "application1" should be
replaced with the value of the "path" attribute of the iisApp
provider in the manifest.xml file. Web PI and other installers will
use this data to suggest a Web Site location for the installation,
when they do not already know where the user wants to install the
application. This is a required tag. There must be at least one
parameter that has this tag, and that specifies the iisApp provider
as its target.
-->
<parameter
name="Application Path"
description="Full site path where you would like to install ocPortal (for example, Default Web Site/ocportal)."
defaultValue="Default Web Site/ocportal"
tags="iisapp"
>
<parameterEntry
type="ProviderPath"
scope="iisapp"
match="ocportal"
/>
</parameter>
<!-- Prompts for database server name, this is used in the
connection string parameter later
-->
<parameter
name="Database Server"
description="Location of your database server (i.e. server name, IP address, or server\instance)"
defaultValue="localhost"
tags="MySQL, dbServer"
>
</parameter>
<!-- Prompts for the database name and fills it into the database
scripts
-->
<!-- #ocPortal - Note that there are two "parameterEntry" elements.
the Web Deployment Tool needs a unique parameterEntry element for
each combination of type, scope and match where a parameter
replacement is required.
-->
<parameter
name="Database Name"
description="Name of the database for your ocPortal installation."
defaultValue="ocportal"
tags="MySQL, dbName"
>
<parameterEntry
type="TextFile"
scope="user.sql"
match="PlaceHolderForDb"
/>
<parameterEntry
type="TextFile"
scope="info.php"
match="PlaceHolderForDb"
/>
</parameter>
<!-- The Database Username is the user id that is used by the
application to communicate with the database. It is usually not
part of the connectionString for running SQL scripts from the Web
Deployment Tool. However, some UIs (including the WebPI) will use
this parameter for the connectionString when the user states that
the database for the application already exists.
-->
<!-- #ocPortal - The Database Username is used in the user.sql
script to GRANT privileges to the user here.
-->
<parameter
name="Database Username"
description="User name to access your ocPortal database."
defaultValue="ocportalUser"
tags="MySQL, dbUsername"
>
<parameterEntry
type="TextFile"
scope="user.sql"
match="PlaceHolderForUser"
/>
<parameterEntry
type="TextFile"
scope="info.php"
match="PlaceHolderForUser"
/>
</parameter>
<!-- This is the password that corresponds to the Database Username.
The install.sql script will set the users password to this value.
-->
<parameter
name="Database Password"
description="Password for the database username."
tags="New, Password, MySQL, dbUserPassword"
>
<parameterEntry
type="TextFile"
scope="info.php"
match="PlaceHolderForPassword"
/>
<parameterEntry
type="TextFile"
scope="user.sql"
match="PlaceHolderForPassword"
/>
</parameter>
<!-- Prompts for the admin credentials and uses them for the
database connection string. This is used to create a login and
assign permissions. The MySQL tag indicates it is a parameter
required for MySQL. The DbAdminUsername tag indicates it should be
used when the user is creating a new database. If they are not, it
can be filled in with the DbUsername value. The UI should be able
to figure out whether or not the user needs to be prompted for this.
-->
<!-- #ocPortal - For ocPortal, there are a number of other database
scripts that will be run as well. They will all be run using the
database administrator credentials. If the ocPortal team decides
that these other scripts should be run as the database user instead,
then they would need to construct a second connectionString (see
notes on connectionString below).
-->
<parameter
name="Database Administrator"
description="Administrator user name for your database."
defaultValue="root"
tags="MySQL, dbAdminUsername"
>
</parameter>
<!-- This is the password that corresponds to the Database
Adminsitrator.
-->
<parameter
name="Database Administrator Password"
description="Password for the database administrator account."
tags="Password, MySQL, dbAdminPassword"
>
</parameter>
<!-- #ocPortal - This is an ocPortal specific parameter.
-->
<parameter
name="config editor password"
description="Password for the ocPortal config editor."
tags="New, Password"
>
<parameterEntry
type="TextFile"
scope="info.php"
match="PlaceHolderForConfigPassword" />
</parameter>
<!-- This is the hidden admin connection string used to run the
database scripts. Note that this connection string is just used
here, and will probably be different from the connection string that
is used by the application itself.
-->
<!-- #ocPortal - Note that each SQL script has a dedicated
parameterEntry. The scope for these matches the provider type in
the manifest.xml file. The match is a regular expression for the
value of the path attribute of the provider.
The user.sql script should be run using admistrative credentials.
If the ocPortal team wanted to use the database user credentials for
running the other scripts, they could do so by creating a second
Connection String parameter. This one would require a different
name than "Connection String". and the default value would be
changed to:
defaultValue="Server={Database Server};Database={Database Name};uid={Database Username};Pwd={Database Password};"
Then the parameterEntries for the scripts that should be run by the
Database User would be moved to be part of this second Connection
String parameter.
-->
<parameter
name="Connection String"
description="Automatically sets the connection string for the connection request."
defaultValue="Server={Database Server};Database={Database Name};uid={Database Administrator};Pwd={Database Administrator Password};"
tags="Hidden"
>
<parameterEntry
type="ProviderPath"
scope="dbmysql"
match="user.sql"
/>
<parameterEntry
type="ProviderPath"
scope="dbmysql"
match="install1.sql"
/>
<parameterEntry
type="ProviderPath"
scope="dbmysql"
match="install2.sql"
/>
<parameterEntry
type="ProviderPath"
scope="dbmysql"
match="install3.sql"
/>
<parameterEntry
type="ProviderPath"
scope="dbmysql"
match="install4.sql"
/>
</parameter>
<!-- This is the parameter that is used to set the ACL for the
files directory. Note that the {Application Path} in the
defaultValue below gets expanded to the ocportal Path entered
by the user. The name of this variable (in the {}s) matches the
parameter name above. The user is never prompted for this -
the Web Deployment Tool has all it needs to generate this.
Also, note that the match attribute is a regular expression to
identify the path for the setAcl directive in the manifest.xml
that this substitution should apply to.
-->
<parameter
name="SetAclParameter1"
description="Sets the ACL on the right file"
defaultValue="{Application Path}/uploads"
tags="Hidden"
>
<parameterEntry
type="ProviderPath"
scope="setAcl"
match="ocportal/uploads"
/>
</parameter>
</parameters>
Sample web.config file
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<system.webServer>
<defaultDocument>
<files>
<remove value="index.php" />
<add value="index.php" />
</files>
</defaultDocument>
</system.webServer>
</configuration>