Blame Manuals/Tcar-ug/Repository/Workstation/config.docbook

d2638e
<sect1 id="repo-ws-config">
eebdc3
eebdc3
    <title>Configuring Your Workstation</title>
eebdc3
eebdc3
    <para>
d75ffe
        Once your workstation has been installed, it is time for you
d75ffe
        to configure it. The configuration of your workstation
d75ffe
        consists on defining your workplace, download a working copy
d75ffe
        from &TCAR; and finally, run the <function>prepare</function>
9c8948
        functionality of <command>centos-art.sh</command> script to
a23299
        install/update the software needed, render images, create
9c8948
        links, and anything else needed.
eebdc3
    </para>
eebdc3
d2638e
    <sect2 id="repo-ws-config-wp">
74d256
    <title>Define Your Workplace</title>
eebdc3
    <para>
eebdc3
        Once you've installed the workstation and it is up and
74d256
        running, you need to register the user name you'll use for
74d256
        working. In this task you need to use the commands
eebdc3
        <command>useradd</command> and <command>passwd</command> to
eebdc3
        create the user name and set a password for it, respectively.
eebdc3
        These commands require administrative privileges to be
bf1a98
        executed, so you need to login as <quote>root</quote>
eebdc3
        superuser for doing so. 
eebdc3
    </para>
eebdc3
eebdc3
    <caution>
eebdc3
    <para>
bf1a98
        Do not use the <quote>root</quote> username for regular
74d256
        tasks inside your working copy of &TCAR;.  This is dangerous
74d256
        and might provoke unreversable damages to your workstation.
eebdc3
    </para>
eebdc3
    </caution>
eebdc3
eebdc3
    <para>
74d256
        When you've registered your user name in the workstation, it
74d256
        provides an identifier for you to open a user's session in the
74d256
        workstation and a place to store the information you produce,
74d256
        as well. This place is known as your home directory and is
74d256
        unique for each user registered in the workstation. For
74d256
        example, if you register the user name john in your
74d256
        workstation, your home directory would be located at 
74d256
        class="directory">/home/john/</filename>.
74d256
    </para>
74d256
    
74d256
    <para>
a382c3
        At this point it is important to define where to download the
a382c3
        working copy of &TCAR; inside your home directory.  This
a382c3
        desition deserves special attention and should be implemented
6e10b7
        carefully in order to grant a standard environment that could
6e10b7
        be distributed.  Let's see some alternatives.
eebdc3
    </para>
eebdc3
74d256
    <sect3>
6e7231
    <title>Different absolute paths</title>
eebdc3
    <para>
74d256
        Consider that you store your working copy under 
74d256
        class="directory">/home/john/Projects/artwork/</filename> and
74d256
        I store mine under 
74d256
        class="directory">/home/al/Projects/artwork/</filename>, we'll
74d256
        end up refering the same files inside our working copies
a382c3
        through different absolute paths.  This alternative generates
a382c3
        a contradiction when files which hold path information inside
a382c3
        are committed up to the central repository from different
a382c3
        working copies. The contradiction comes from the question:
a382c3
        which is the correct absolute path to use inside such files,
a382c3
        yours or mine? (None of them is, of course.)
74d256
    </para>
74d256
74d256
    </sect3>
eebdc3
74d256
    <sect3 id="repo-ws-config-wp-OneUniqueAbsolutePath">
6e7231
    <title>One unique absolute path</title>
eebdc3
    <para>
c03f46
        Another case would be that where you and I ourselves use one
c03f46
        unique home directory (e.g., 
74d256
        class="directory">/home/centos/Projects/artwork/</filename>)
74d256
        to store the working copy of &TCAR; in our own workstations,
74d256
        but configure the subversion client to use different user
74d256
        names to commit changes up from the working copy to the
a382c3
        central repository.  This alternative might be not so good in
a382c3
        situations where you and I have to share the same workstation.
a382c3
        In such cases, it would be required that we both share the
a382c3
        password information of the same system user (the
6feca0
        <quote>centos</quote> user in our example) which, in
a382c3
        addition, gives access to that user's subversion client
a382c3
        configuration and this way provokes the whole sense of using
a382c3
        different subversion credentials for committing changes to be
a382c3
        lost.
74d256
    </para>
74d256
    </sect3>
eebdc3
74d256
    <sect3>
6e7231
    <title>Different absolute paths through dynamic expansion</title>
eebdc3
    <para>
74d256
        Most of the absolute paths we use inside the working copy are
74d256
        made of two parts, one dynamic and one relative fixed. The
74d256
        dynamic part is the home directory of the current user and its
74d256
        value can be retrived from the <envar>$HOME</envar>
74d256
        environment variable.  The fixed part of the path is the one
74d256
        we set inside the repositroy structure itself as a matter of
74d256
        organization.  What we need here is to find a way to expand
74d256
        variables inside files that don't support variable expansion.
74d256
        This alternative had worked rather fine when we produce
a382c3
        produce PNG files from SVG files and XTHML from DocBook files,
a382c3
        but the same is not true for absolute paths inside files that
a382c3
        are used as in their permanent state inside the repository
a382c3
        (e.g., CSS files and other files similar in purpose).
eebdc3
    </para>
74d256
    </sect3>
74d256
6e7231
    <sect3>
6e7231
    <title>Different absolute paths, dynamic expansion, symbolic
6e7231
    links, relative links, and environment variables</title>
6e7231
6e7231
    <para>
6e7231
        With this solution it is possible to store working copies of
6e7231
        &TCAR; on different locations inside the same workstation
6e7231
        without lose relation between files. Here we use the
6e7231
        TCAR_WORKDIR environment variable to set the location of the
6e7231
        working copy inside the workstation. Later the centos-art.sh
6e7231
        scripts uses this value as reference to determine where the
6e7231
        working copy is. This value is also the one used for dynamic
6e7231
        expansion inside design models and other similar files. In the
6e7231
        case of web projects where different components are required
6e7231
        to produce the final content, we create symbolic links between
6e7231
        them and use relative paths so it is possible to reuse them
6e7231
        and retain the relation between them in different contexts.
6e7231
    </para>
6e7231
6e7231
    <para>
6e7231
        For example, lets consider the organization of XHTML manuals
6e7231
        rendered from DocBook source files. When you render a DocBook
6e7231
        manual inside &TCAR; it creates XHTML files.  This XHTML files
6e7231
        use images and common style sheets for better presentation.
6e7231
        Both of these images and styles components live outside the
6e7231
        XHTML structure so, in order to make them available
6e7231
        relatively to the XHTML structure, we created symbolic links
6e7231
        from the XHTML structure to the outside location where they
6e7231
        are in. The creation of symbolic links takes place
6e7231
        automatically when each DockBook manual is rendered through
6e7231
        <command>centos-art.sh</command>, which uses the value of
6e7231
        TCAR_WORKDIR environment variable as reference to determine
6e7231
        the absolute path of the working copy.
6e7231
    </para>
6e7231
6e7231
    <para>
6e7231
        Bacause absolute paths are no longer stored inside permanent
6e7231
        files and <command>centos-art.sh</command> script uses the
6e7231
        TCAR_WORKDIR environment variable to determine where the
6e7231
        working copy is stored in the workstation, it should be safe
6e7231
        to download working copies of &TCAR; anywhere in the
6e7231
        workstation. One just have to be sure that the value of
6e7231
        TCAR_WORKDIR environment variable does match the location of
6e7231
        the working copy you are using.
6e7231
    </para>
6e7231
6e7231
    </sect3>
6e7231
74d256
    </sect2>
74d256
74d256
    <sect2 id="repo-ws-config-wc">
74d256
    <title>Download Your Working Copy</title>
74d256
74d256
    <para>
6e7231
        In order to use &TCAR; you need to download a working copy
6e7231
        from the central repository into your workstation.  To
6e7231
        download such working copy use the following command:
74d256
    </para>
74d256
6e7231
    <screen>svn co https://projects.centos.org/svn/artwork ~/</screen>
6e7231
6e7231
    <para>
6e7231
        This command will create your working copy inside your home
6e7231
        directory, specifically in a directory named 
6e7231
        class="directory">artwork</filename>. Inside this directory
6e7231
        you will find all the files you need to work with inside
6e7231
        &TCAR;. If you want to have your working copy in a location
6e7231
        different to that one shown above, see 
6e7231
        linkend="repo-ws-config-ChangeWorkingCopy" />.
6e7231
    </para>
c03f46
eebdc3
    <para>
74d256
        The first time you download the working copy it contains no
74d256
        image files, nor documentation, or localized content inside
74d256
        it. This is because all the files provided in the working copy
74d256
        are source files (e.g., the files needed to produce other
6e7231
        files) and it is up to you to render them in order to produce
6e7231
        the final files (e.g., images and documentation) used to
6e7231
        implement &TCPCVI;.
eebdc3
    </para>
eebdc3
9c8948
    </sect2>
9c8948
9c8948
    <sect2 id="repo-ws-config-sudoers">
9c8948
    <title>Configure Administrative Tasks</title>
9c8948
9c8948
    <para>
9c8948
        Most of the administrative tasks you need to perform in your
9c8948
        working copy of &TCAR; are standardized inside the
9c8948
        <function>prepare</function> functionality of
9c8948
        <command>centos-art.sh</command> script. Inside
9c8948
        <command>centos-art.sh</command>
6e7231
        script, all administrative task are invoked through the
9c8948
        <command>sudo</command> command. Thus, in order for the
9c8948
        <command>centos-art.sh</command> script to perform
9c8948
        administrative tasks, you need to update the
9c8948
        <command>sudo</command>'s configuration in a way that such
9c8948
        administrative actions be allowed.
9c8948
    </para>
9c8948
9c8948
    <para>
9c8948
        At time of this writing the <command>centos-art.sh</command>
9c8948
        script implements just one administrative task, that is
9c8948
        package management.  Nevertheless, in the future, other
6e7231
        administrative tasks might be included as well (e.g.,
6e7231
        installing themes locally from the working copy for testing
6e7231
        purposes.).
9c8948
    </para>
9c8948
eebdc3
    <para>
9c8948
       To update the <command>sudo</command>'s configuration, execute
9c8948
       the <command>visudo</command> command as <quote>root</quote>.
9c8948
       Later, uncoment the <varname>Cmnd_Alias</varname> related to
6e7231
       <quote>SOFTWARE</quote> and add a line for your username
6e7231
       allowing software commands. This configuration is illustrated
6e7231
       in <xref linkend="repo-ws-config-sudoers-example" />.
eebdc3
    </para>
eebdc3
9c8948
    <example id="repo-ws-config-sudoers-example">
9c8948
    <title>The <filename>/etc/sudoers</filename> configuration file</title>
9c8948
    <screenshot>
9c8948
    <screeninfo><filename>/etc/sudoers</filename> configuration file</screeninfo>
9c8948
    <mediaobject>
9c8948
    <textobject>
9c8948
<programlisting>
9c8948
## Installation and management of software
9c8948
Cmnd_Alias SOFTWARE = /bin/rpm, /usr/bin/up2date, /usr/bin/yum
9c8948
9c8948
## Next comes the main part: which users can run what software on
9c8948
## which machines (the sudoers file can be shared between multiple
9c8948
## systems).
9c8948
## Syntax:
9c8948
##
9c8948
##      user    MACHINE=COMMANDS
9c8948
##
9c8948
## The COMMANDS section may have other options added to it.
9c8948
##
9c8948
## Allow root to run any commands anywhere
9c8948
root    ALL=(ALL)       ALL
9c8948
9c8948
## Allow the centos user to run installation and management of
9c8948
## software anywhere.
6e7231
al      ALL=(ALL)       SOFTWARE
9c8948
</programlisting>
9c8948
    </textobject>
9c8948
    </mediaobject>
9c8948
    </screenshot>
9c8948
    </example>
9c8948
    
9c8948
    </sect2>
9c8948
9c8948
    <sect2 id="repo-ws-config-runout">
6e7231
    <title>Run Preparation Tool</title>
9c8948
    <para>
6e7231
        Once you've both downloaded a working copy from &TCAR; 
6e7231
        and configured the <command>sudo</command>'s configuration
6e7231
        file successfully, run the <function>prepare</function>
6e7231
        functionality of <command>centos-art.sh</command> script to
6e7231
        complete the configuration process using the following
6e7231
        command:
9c8948
    </para>
9c8948
6e7231
    <screen>~/artwork/trunk/Scripts/Bash/centos-art.sh prepare</screen>
9c8948
9c8948
    <para>
9c8948
        To know more about the <function>prepare</function>
9c8948
        functionality of <command>centos-art.sh</command> script, see
9c8948
        <xref linkend="scripts-bash-prepare" />.
9c8948
    </para>
eebdc3
    </sect2>
eebdc3
6e7231
    <sect2 id="repo-ws-config-ChangeWorkingCopy">
6e7231
    <title>Changing Your Working Copy Default Path</title>
6e7231
    <para>
6e7231
        By default your working copy should be store in your home
6e7231
        directory, specifically in the location 
6e7231
        class="directory">~/artwork</filename>. This location may not
6e7231
        be the final location where you want to have your working copy
6e7231
        in situations where you are working on several projects at the
6e7231
        same time or you already have a define location to organize
6e7231
        your projects inside your home directory. Thus, you may need
6e7231
        to change the default location of your working copy to a more
6e7231
        appropriate location.
6e7231
    </para>
6e7231
    
6e7231
    <para>
6e7231
        The default path to your working copy is controlled by the
6e7231
        <envar>TCAR_WORKDIR</envar> environment variable. This
6e7231
        variable is firstly defined in your personal profile after
6e7231
        running the prepare functionality of
6e7231
        <command>centos-art.sh</command> script. So, to change the
6e7231
        path of your working copy correctly, do the following:
6e7231
    </para>
6e7231
6e7231
    <orderedlist>
6e7231
    <listitem>
6e7231
    <para>
6e7231
        Create the parent directory you will use to store your working
6e7231
        copy. For example: 
6e7231
        <screen>mkdir -p ~/Projects/CentOS</screen>
6e7231
    </para>
6e7231
    </listitem>
6e7231
    <listitem>
6e7231
    <para>
6e7231
        Move the currently downloaded working copy from ~/artwork to
6e7231
        your new location. For example: 
6e7231
        <screen>mv ~/artwork ~/Projects/CentOS/</screen>
6e7231
    </para>
6e7231
    </listitem>
6e7231
    <listitem>
6e7231
    <para>
6e7231
       Edit <filename>~/.bash_profile</filename> file to set the new
6e7231
       location (without trailing slash) of your working copy as value
6e7231
       of TCAR_WORKDIR environment variable. For example:
6e7231
       <screen>TCAR_WORKDIR=${HOME}/Projects/CentOS/artwork</screen>
6e7231
    </para>
6e7231
    </listitem>
6e7231
    <listitem>
6e7231
    <para>
6e7231
        Do log out from your active user's seesion and do log in again
6e7231
        so the environment changes take effect. Or just update the
6e7231
        current environment information by running the following
6e7231
        command:
6e7231
        <screen>. ~/.bash_profile</screen>
6e7231
    </para>
6e7231
    </listitem>
6e7231
    <listitem>
6e7231
    <para>
6e7231
        Update internal links by running the following command:
6e7231
        <screen>${TCAR_WORKDIR}/trunk/Scripts/Bash/centos-art.sh prepare --links</screen>
6e7231
    </para>
6e7231
    </listitem>
6e7231
    </orderedlist>
6e7231
6e7231
    </sect2>
6e7231
eebdc3
</sect1>