Changes between Version 1 and Version 2 of TracEnvironment

Timestamp:

06/10/10 13:36:28 (14 years ago)

Author:

trac

Comment:

--

TracEnvironment

@@ -5 +5 @@
 == Creating an Environment ==
 
-A new Trac environment is created using [wiki:TracAdmin trac-admin]:
+A new Trac environment is created using  [wiki:TracAdmin trac-admin]:
 {{{
-$ trac-admin /path/to/projectenv initenv
+$ trac-admin /path/to/myproject initenv
 }}}
 
@@ -18 +18 @@
 the appropriate permissions. The same applies to the Subversion repository 
 Trac is eventually using, although Trac will only require read access as long 
-as you're not using the BDB file system.''
+as you're not using the BDB file system. Also, it seems that project names
+with spaces can be problematic for authentication (see [trac:#7163]).''
+
+''Note: "initenv" when using svn repository does not imply that trac-admin will perform "svnadmin create" for the specified repository path. You need to perform the "svnadmin create" prior to trac-admin initenv if you're creating a new svn repository altogether with a new trac environment, otherwise you will see a message "Warning: couldn't index the repository" when initializing the environment.''
 
 == Database Connection Strings ==
 
-Since version 0.9, Trac supports both [http://sqlite.org/ SQLite],
-[http://www.postgresql.org/ PostgreSQL] and [http://mysql.com/ MySQL] as
-database backends.  The default is to use SQLite, which is probably sufficient
-for most projects. The database file is then stored in the environment
-directory, and can easily be [wiki:TracBackup backed up] together with the
-rest of the environment.
+Since version 0.9, Trac supports both [http://sqlite.org/ SQLite] and
+[http://www.postgresql.org/ PostgreSQL] database backends.  Preliminary
+support for [http://mysql.com/ MySQL] was added in 0.10.  The default is
+to use SQLite, which is probably sufficient for most projects. The database
+file is then stored in the environment directory, and can easily be 
+[wiki:TracBackup backed up] together with the rest of the environment.
 
+=== Embedded SQLite Connection String ===
 The connection string for an embedded SQLite database is:
 {{{
@@ -34 +38 @@
 }}}
 
+=== PostgreSQL Connection String ===
 If you want to use PostgreSQL or MySQL instead, you'll have to use a
 different connection string. For example, to connect to a PostgreSQL
@@ -41 +46 @@
 postgres://johndoe:letmein@localhost/trac
 }}}
+''Note that due to the way the above string is parsed, the "/" and "@" characters cannot be part of the password.''
 
 If PostgreSQL is running on a non-standard port (for example 9342), use:
@@ -47 +53 @@
 }}}
 
+On UNIX, you might want to select a UNIX socket for the transport,
+either the default socket as defined by the PGHOST environment variable:
+{{{
+postgres://user:password@/database
+}}}
+or a specific one:
+{{{
+postgres://user:password@/database?host=/path/to/socket/dir
+}}}
+
 Note that with PostgreSQL you will have to create the database before running
 `trac-admin initenv`.
 
-And make sure PostgreSQl DB name is "trac". What worked for me:
-And didn't work uppercase trac-user-name
+See the [http://www.postgresql.org/docs/ PostgreSQL documentation] for detailed instructions on how to administer [http://postgresql.org PostgreSQL].
+Generally, the following is sufficient to create a database user named `tracuser`, and a database named `trac`.
 {{{
-sudo su - postgres -c createdb trac
-sudo su - postgres -c psql trac
-CREATE USER trac-user-name WITH PASSWORD 'trac-pass-name';
+createuser -U postgres -E -P tracuser
+createdb -U postgres -O tracuser -E UTF8 trac
+}}}
+When running `createuser` you will be prompted for the password for the user 'tracuser'. This new user will not be a superuser, will not be allowed to create other databases and will not be allowed to create other roles. These privileges are not needed to run a trac instance. If no password is desired for the user, simply remove the `-P` and `-E` options from the `createuser` command.  Also note that the database should be created as UTF8. LATIN1 encoding causes errors trac's use of unicode in trac.  SQL_ASCII also seems to work.
+
+Under some default configurations (debian) one will have run the `createuser` and `createdb` scripts as the `postgres` user.  For example:
+{{{
+sudo su - postgres -c 'createuser -U postgres -S -D -R -E -P tracuser'
+sudo su - postgres -c 'createdb -U postgres -O tracuser -E UTF8 trac'
 }}}
 
-(Just to remind you, if you don't have a sudo/su setup, you just need to do the createdb and psql statements. That threw me the first couple of times I read this.)
+Trac uses the `public` schema by default but you can specify a different schema in the connection string:
+{{{
+postgres://user:pass@server/database?schema=yourschemaname
+}}}
+
+=== MySQL Connection String ===
+
+If you want to use MySQL instead, you'll have to use a
+different connection string. For example, to connect to a MySQL
+database on the same machine called `trac`, that allows access to the
+user `johndoe` with the password `letmein`, the mysql connection string is:
+{{{
+mysql://johndoe:letmein@localhost:3306/trac
+}}}
 
 == Source Code Repository ==
@@ -98 +133 @@
  * `db`
    * `trac.db` - The SQLite database (if you're using SQLite).
- * `plugins` - Environment-specific [wiki:TracPlugins plugins] (Python eggs)
- * `templates` - Custom environment-specific templates.
-   * `site_css.cs` - Custom CSS rules.
-   * `site_footer.cs` - Custom page footer.
-   * `site_header.cs` - Custom page header.
- * `wiki-macros` - Environment-specific [wiki:WikiMacros Wiki macros].
+ * `htdocs` - directory containing web resources, which can be referenced in Genshi templates. '''''(0.11 only)'''''
+ * `log` - default directory for log files, if logging is turned on and a relative path is given.
+ * `plugins` - Environment-specific [wiki:TracPlugins plugins] (Python eggs, since [trac:milestone:0.10 0.10])
+ * `templates` - Custom Genshi environment-specific templates. '''''(0.11 only)'''''
+   * `site.html` - method to customize header, footer, and style, described in TracInterfaceCustomization#SiteAppearance
+ * ''`templates` - Custom [trac:ClearSilver ClearSilver] environment-specific templates. '''(0.10 only)''' ''
+   * ''`site_css.cs` - Custom CSS rules.''
+   * ''`site_footer.cs` - Custom page footer.''
+   * ''`site_header.cs` - Custom page header.''
+ * ''`wiki-macros` - Environment-specific [WikiMacros Wiki macros]. '''(0.10 only)''' ''
 
   '''Note: don't confuse a Trac environment directory with the source code repository directory.