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

d2638e
<sect1 id="repo-ws-config">
eebdc3
eebdc3
    <title>Configuring Your Workstation</title>
eebdc3
eebdc3
    <para>
eebdc3
        Once your worstation is installed, it is time for you to
eebdc3
        configure it.  At this point you create a user for everyday's
eebdc3
        work, configure third party repositories, fix environment
eebdc3
        variables to fit your personal needs, download the working
eebdc3
        copy of &TCAR; and prepare it for start using it.
eebdc3
    </para>
eebdc3
d2638e
    <sect2 id="repo-ws-config-wp">
d2638e
    <title>Workplace</title>
eebdc3
    <para>
eebdc3
        Once you've installed the workstation and it is up and
eebdc3
        running, you need to create the user name you'll use for your
eebdc3
        everyday's work. 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
eebdc3
        executed, so you need to login as <emphasis>root</emphasis>
eebdc3
        superuser for doing so. 
eebdc3
    </para>
eebdc3
eebdc3
    <caution>
eebdc3
    <para>
eebdc3
        Do not use the <emphasis>root</emphasis> username for your
eebdc3
        everyday's work inside your working copy of &TCAR;.  This is
c98021
        dangerous and might provoke unreversable damages to your
eebdc3
        workstation.
eebdc3
    </para>
eebdc3
    </caution>
eebdc3
eebdc3
    <para>
eebdc3
        When user names are created inside the workstation, it doesn't
eebdc3
        create only a user identifier for you to login, but a place
eebdc3
        for you to store your information, as well. This place is
eebdc3
        known as your home directory and is unique for each user
c03f46
        inside the workstation.  At this point, it is necessary to
c03f46
        decide where the working copy tree will be stored in the
c03f46
        workstation filesystem.
eebdc3
    </para>
eebdc3
eebdc3
    <para>
c03f46
        <emphasis>Case 1: Different Home Directories</emphasis>
c03f46
        — Assuming you store your working copy under 
eebdc3
        class="directory">/home/john/artwork/</filename> and I store
eebdc3
        mine under 
eebdc3
        class="directory">/home/al/artwork/</filename>, we'll end up
eebdc3
        refering the same files inside our working copies through
eebdc3
        different absolute paths. This generates a contradiction when
eebdc3
        files, holding path information inside, are committed up to
eebdc3
        the central repository. The contradiction comes from the
eebdc3
        question: which is the correct absolute path to use inside
c03f46
        such files, yours or mine? (None of them is, of course.)
eebdc3
    </para>
eebdc3
eebdc3
    <para>
c03f46
        <emphasis>Case 2: One Unique Home Directory</emphasis> —
c03f46
        Another case would be that where you and I ourselves use one
c03f46
        unique home directory (e.g., 
eebdc3
        class="directory">/home/centos/artwork/</filename>) to store
eebdc3
        the working copy of &TCAR; in our own workstations, but
eebdc3
        configure the subversion client to use different user names to
eebdc3
        commit changes up from the working copy to the central
eebdc3
        repository.  This configuration might be not so good for
eebdc3
        situations where you and I have to share the same workstation.
eebdc3
        In such case, it would be required that we both share the
eebdc3
        password information of the same system user (the
eebdc3
        <emphasis>centos</emphasis> user in our example) which, in
eebdc3
        addition, gives access to that user's subversion client
eebdc3
        configuration and this way provokes the whole sense of using
eebdc3
        different subversion credentials for committing changes to be
eebdc3
        lost.
eebdc3
    </para>
eebdc3
eebdc3
    <para>
c03f46
        <emphasis>Case 3: Different Home Directories Through Dynamic
c03f46
        Expansion</emphasis> — Most of the absolute paths we use
c03f46
        inside the working copy are made of two parts, one dynamic and
c03f46
        one fixed. The dynamic part is the home directory of the
c03f46
        current user and its value can be retrived from the
c03f46
        <envar>$HOME</envar> environment variable.  The fixed part of
c03f46
        the path is the one we set inside the repositroy structure
c03f46
        itself as organization matter.  What we need here is to find a
c03f46
        way to expand variables inside files that don't support
c03f46
        variable expansion.  So far we've been doing this through
c03f46
        creation template instances which are temporal files with
c03f46
        translation markers expanded inside.  This work rather fine
c03f46
        with template files that are one-time-pass (e.g., when we
c03f46
        produce produce PNG files from SVG files and XTHML from
c03f46
        DocBook files), but the same is not true for absolute paths
c03f46
        inside files that are used as in their permanent state inside
c03f46
        the repository (e.g., CSS files and other files similar in
c03f46
        purpose).
eebdc3
    </para>
c03f46
eebdc3
    <para>
eebdc3
        From the three cases discussed above, the second one (i.e.,
eebdc3
        One unique home directory) seems to be the best candidate. It
eebdc3
        limits us from using more than one working copy in the same
eebdc3
        workstation, but gives us the chance of standardizing the use
eebdc3
        of absolute paths inside all the working copies of &TCAR;.
eebdc3
        Using absolute paths is very convenient because it is possible
eebdc3
        to reuse information from different locations inside the
eebdc3
        working copy, something that would be almost imposible to
eebdc3
        maintain if relative paths were used instead. Thus, lets
eebdc3
        assume the second case of handling home directories as default
eebdc3
        solution to relatively solve the problem of where to store
eebdc3
        working copies of &TCAR; until a better one shows itself up.
eebdc3
    </para>
eebdc3
eebdc3
    <para>
eebdc3
        The action of providing working copies of &TCAR; that permit
eebdc3
        to reuse files inside them unifies the way content is produced
eebdc3
        inside the working copy and provides a convenction for people
eebdc3
        working on different areas to get attached to in order to
eebdc3
        syncronize their works and still keep doing it decentralized
eebdc3
        one another.
eebdc3
    </para>
eebdc3
eebdc3
    </sect2>
eebdc3
d2638e
    <sect2 id="repo-ws-config-envar">
d2638e
    <title>Environment Variables</title>
eebdc3
eebdc3
    <para>
eebdc3
        Once you've created the <emphasis>centos</emphasis> user name
eebdc3
        for your everyday's work and you had done login with it, there
eebdc3
        are some environment variables that you can customize to fit
eebdc3
        your personal needs (e.g., default text editor, default locale
eebdc3
        information, default time zone representation, etc.).  To
eebdc3
        customize these variables you need to edit your personal
eebdc3
        profile (i.e., 
eebdc3
        class="directory">~/.bash_profile</filename>) and set the
eebdc3
        redefinition there.  Notice that you may need to logout and
eebdc3
        then do login again in order for the new variable values to
eebdc3
        take effect.
eebdc3
    </para>
eebdc3
eebdc3
    <variablelist>
eebdc3
    <varlistentry>
eebdc3
    <term>Default text editor</term>
eebdc3
    <listitem>
eebdc3
    <para>
eebdc3
        The default text editor information is controlled by the
eebdc3
        <envar>EDITOR</envar> environment variable. The
eebdc3
        <command>centos-art.sh</command> script uses the default text
eebdc3
        editor to edit subversion pre-commit messages, translation
eebdc3
        files, documentation files, script files, and similar
eebdc3
        text-based files.
eebdc3
    </para>
eebdc3
eebdc3
    <para>
eebdc3
        If <envar>EDITOR</envar> environment variable is not set,
eebdc3
        <command>centos-art.sh</command> script uses 
eebdc3
        class="directory">/usr/bin/vim</filename> as default text
eebdc3
        editor. Otherwise, the following values are recognized by
eebdc3
        <command>centos-art.sh</command> script:
eebdc3
eebdc3
        <itemizedlist>
eebdc3
        <listitem>
eebdc3
        <para>
eebdc3
            <filename class="directory">/usr/bin/vim</filename>
eebdc3
        </para>
eebdc3
        </listitem>
eebdc3
eebdc3
        <listitem>
eebdc3
        <para>
eebdc3
        <filename class="directory">/usr/bin/emacs</filename>
eebdc3
        </para>
eebdc3
        </listitem>
eebdc3
eebdc3
        <listitem>
eebdc3
        <para>
eebdc3
            <filename class="directory">/usr/bin/nano</filename>
eebdc3
        </para>
eebdc3
        </listitem>
eebdc3
        </itemizedlist>
eebdc3
eebdc3
    </para>
eebdc3
eebdc3
    <para>
eebdc3
        If no one of these values is set in the <envar>EDITOR</envar>
eebdc3
        environment variable, the <command>centos-art.sh</command>
eebdc3
        script uses 
eebdc3
        class="directory">/usr/bin/vim</filename> text editor, the one
eebdc3
        installed by default in &TC;;. 
eebdc3
    </para>
eebdc3
    </listitem>
eebdc3
    </varlistentry>
eebdc3
eebdc3
    <varlistentry>
eebdc3
    <term>Default locale information</term>
eebdc3
    <listitem>
eebdc3
    <para>
eebdc3
        The default locale information is controlled by the
eebdc3
        <envar>LANG</envar> environment variable. This variable is
eebdc3
        initially set in the installation process of &TC;;,
eebdc3
        specifically in the <emphasis>Language</emphasis> step.
eebdc3
        Generally, there is no need to customize this variable in your
eebdc3
        personal profile. If you need to change the value of this
eebdc3
        environment variable do it through the login screen of GNOME
eebdc3
        Desktop Environment or the
eebdc3
        <command>system-config-language</command> command.
eebdc3
    </para>
eebdc3
eebdc3
    <para>
eebdc3
        The <command>centos-art.sh</command> script uses the
eebdc3
        <envar>LANG</envar> environment variable to determine what
eebdc3
        language to use for printing output messages from the script
eebdc3
        itself, as well as the portable objects locations that need to
eebdc3
        be updated or edited when you localize directory structures
eebdc3
        inside the working copy of &TCAR;.
eebdc3
    </para>
eebdc3
    </listitem>
eebdc3
    </varlistentry>
eebdc3
eebdc3
    <varlistentry>
eebdc3
    <term>Default time zone representation</term>
eebdc3
    <listitem>
eebdc3
    <para>
eebdc3
        The time zone representation is a time correction applied to
eebdc3
        the system time (stored in the BIOS clock) based on your
eebdc3
        country location.  This correction is specially useful to
eebdc3
        distributed computers around the world that work together and
eebdc3
        need to be syncronized in time to know when things happened.
eebdc3
    </para>
eebdc3
    <para>
eebdc3
        &TCAR; is made of one server and several workstations spread
eebdc3
        around the world. In order for all these workstations to know
eebdc3
        when changes in the server took place, it is required that
eebdc3
        they all set their system clocks to use the same time
eebdc3
        information (e.g., through UTC (Coordinated Universal Time))
eebdc3
        and set the time correction for their specific countries in
eebdc3
        the operating system.  Otherwise, it would be difficult to
eebdc3
        know when something exactly happened.
eebdc3
    </para>
eebdc3
    <para>
eebdc3
        Generally, setting the time information is a straight-forward
eebdc3
        task and configuration tools provided by &TC;; do cover time
eebdc3
        correction for most of the countries around the world.
eebdc3
        However, if you need a time precision not provided by any of
eebdc3
        the date and time configuration tools provided by &TC;; then,
eebdc3
        you need to customize the <envar>TZ</envar> environment
eebdc3
        variable in your personal profile to correct the time
eebdc3
        information by yourself.  The format of <envar>TZ</envar>
eebdc3
        environment variable is described in tzset(3)
eebdc3
        manual page.  
eebdc3
    </para>
eebdc3
    </listitem>
eebdc3
    </varlistentry>
eebdc3
    </variablelist>
eebdc3
    </sect2>
eebdc3
d2638e
    <sect2 id="repo-ws-config-sudo">
d2638e
    <title>Administrative Tasks</title>
eebdc3
eebdc3
    <para>
eebdc3
        Sometimes it is necessary that you perform administrative
eebdc3
        tasks inside the workstation the working copy of &TCAR; is
eebdc3
        stored in. These tasks might demand you to type many commands
eebdc3
        (e.g., for configuring a third party repository) or just a
eebdc3
        one-line command (e.g., for installing a new package).  In
eebdc3
        both cases this kind of tasks require permissions that your
eebdc3
        user for everyday's work must not have under no mean. 
eebdc3
    </para>
eebdc3
eebdc3
    <para>
eebdc3
        To perform administrative tasks in your workstation, you need
eebdc3
        to login as <emphasis>root</emphasis> or configure the
eebdc3
        <command>sudo</command> program to temporarily granting the
eebdc3
        permissions your regular user needs to perform the
eebdc3
        administrative tasks. The configuration of
eebdc3
        <command>sudo</command> program is at
eebdc3
        <filename>/etc/sudoers</filename> file and you need to add the
eebdc3
        <emphasis>centos</emphasis> user to the list of privileged
eebdc3
        user as described in the section below:
eebdc3
    </para>
eebdc3
eebdc3
<screen>
eebdc3
## Next comes the main part: which users can run what software on 
eebdc3
## which machines (the sudoers file can be shared between multiple
eebdc3
## systems).
eebdc3
## Syntax:
eebdc3
##
eebdc3
##      user    MACHINE=COMMANDS
eebdc3
##
eebdc3
## The COMMANDS section may have other options added to it.
eebdc3
##
eebdc3
## Allow root to run any commands anywhere 
eebdc3
root    ALL=(ALL)       ALL
eebdc3
centos  ALL=(ALL)       ALL
eebdc3
</screen>
eebdc3
eebdc3
    <para>
eebdc3
        This configuration is required in order for automation scripts
eebdc3
        to realize administrative tasks that otherwise you would need
eebdc3
        to type one by one.  It is worth to mention that all these
eebdc3
        tasks are organized in the <function>prepare</function>
eebdc3
        functionality of the <command>centos-art.sh</command> script
eebdc3
        in the sake of reducing work and standardize the procedure of
eebdc3
        performing them. It is also worth to mention that, the
eebdc3
        <command>centos-art.sh</command> script is available for you
eebdc3
        to run, study, improve and share your changes as described in
eebdc3
        <xref linkend="licenses-gpl" />.
eebdc3
    </para>
eebdc3
    
eebdc3
    </sect2>
eebdc3
d2638e
    <sect2 id="repo-ws-config-wc">
d2638e
    <title>Working Copy</title>
eebdc3
eebdc3
    <para>
eebdc3
        Once you've installed and configured the workstation, it is
eebdc3
        ready to receive the working copy of &TCAR;. In this step, you
eebdc3
        use Subversion's client to communicate the source repository
39143d
        of &TCAR;  and download all the files that make a working copy
39143d
        of it.
eebdc3
    </para>
eebdc3
eebdc3
    <para>
eebdc3
        To download the working copy of &TCAR; you need to login as
eebdc3
        your everyday's work user (i.e., the
eebdc3
        <emphasis>centos</emphasis> user) and use the Subversion
eebdc3
        client installed in your workstation to bring all the files
eebdc3
        you need to work with from the source repository down to your
eebdc3
        workstation, just as the following command describes:
eebdc3
    </para>
eebdc3
eebdc3
    <screen>svn co https://projects.centos.org/svn/artwork ~/</screen>
eebdc3
eebdc3
    <para>
eebdc3
        This command will create your working copy of &TCAR; in your
eebdc3
        workstation, specifically in the 
eebdc3
        class="directory">/home/centos/artwork</filename> directory.
eebdc3
    </para>
eebdc3
39143d
    <note>
eebdc3
    <para>
eebdc3
        If the Subversion's client wasn't installed by default, you
eebdc3
        need to install it using the following command:
eebdc3
    </para>
eebdc3
    <screen>sudo yum install subversion</screen>
39143d
    </note>
39143d
39143d
39143d
    <para>
39143d
        Once your working copy of &TCAR; has been downloaded, you
39143d
        should notice that there is no image files, nor documentation,
39143d
        or localized content inside it. This is because all the files
39143d
        provided in the working copy are source files (e.g., the files
39143d
        needed to produce other files) and it is up to you the action
39143d
        of render them to produce the final files (e.g., images and
8b099e
        documentation) used to implement &TCPCVI;. 
39143d
    </para>
eebdc3
eebdc3
    <para>
39143d
        Another consideration to be aware of at this point, is the
39143d
        need of verifying the software installed in the workstation,
39143d
        as well as the creation of symbolic links to connect the
39143d
        content produced inside the working copy to applications
39143d
        outside it (e.g., to make available patterns, brushes, and
39143d
        palettes produced inside the working copy in GIMP, the
39143d
        application used to manipulate images).
eebdc3
    </para>
eebdc3
eebdc3
    <para>
8b099e
        This final preparation stuff is automated by the
39143d
        <function>prepare</function> functionality of the
39143d
        <command>centos-art.sh</command> script, as described in 
39143d
        linkend="scripts-bash-prepare" />. Execute it right now,
eebdc3
        to be sure your workstation and your working copy are both
eebdc3
        ready to be used.
eebdc3
    </para>
eebdc3
eebdc3
    </sect2>
eebdc3
eebdc3
</sect1>