Como fazer uma instalação básica do MoinMoin no seu sistema.

Conteúdos

Antes de integrar o MoinMoin no seu ambiente web, terá de instalar os ficheiros e dados e o código-fonte do MoinMoin utilizando o mecanismo distutils do Python standard (setup.py). Esta página explica os passos necessários para o fazer. Para mais informações sobre o processo de instalação distutils, consulte o documento Instalar Módulos de Python no seu pacote de documentação de Python.

A instalação é semelhante em Windows e em Linux (e noutros sistemas POSIX-type; para simplificar, apenas escrevemos "Linux" nos documentos).

• Utilizamos texto como > argumentos do comando para mostrar o que tem de escrever na linha de comandos (também conhecida como shell, terminal, etc.). Nos nossos exemplos "> " é o cursos, não tem de o inserir, tem de escrever o que se segue. As linhas que não começam com "> " são as respostas aos comandos que escreveu. Leia-os cuidadosamente.

Verifique se o Python está a funcionar

O MoinMoin necessita que de Python para funcionar. Assim, o primeiro passo deve ser verificar se tem instalada uma versão de Python utilizável, e se esta está correctamente configurada. Se não for este o caso, é necessário corrigir antes de prosseguir.

O ficheiro CHANGES no arquivo do MoinMoin refere as versões suportadas. Python 2.3 é o requisito mínimo para o MoinMoin 1.5, mas sugerimos que utilize a versão de Python mais recente.

Pode descarregar o Python na página http://www.python.org/download/.

Se tem praticamente certeza de que tem uma versão de Python aceitável instalada, mas os comandos indicados em baixo não funcionam, pode ser que os seus ficheiros não estejam no search path (caminho de pesquisa). Este documento não diz como configurar o caminho de pesquisa. Por favor, peça ajuda no seu fórum de discussão de Python, Linux ou Windows favorido.

Se tem acesso shell, é muito fácil verificar se o Python está a funcionar. Basta escrever o comando seguinte, e ver o resultado:

> python -V
Python 2.4.3

Se não tem acesso shell, pode tentar utilizar este script pythontest.cgi (assume que está a utilizar um servidor Web do tipo Linux). Envie o script para a sua directoria cgi-bin, utilize chmod a+rx pythontest.cgi (ou um comando similar no seu programa FTP) para o tornar executável, e invoque-o utilizando o seu navegador Web.

pythontest.cgi

Se não aparecer "CGI scripts work", bem, então os scripts CGI não funcionam. Se não apresenta uma ou mais números de versões de Pyhton, então o Python não está correctamente instalado. Em ambos os casos, antes de prosseguir, tem de entrar em contacto com o administrador do servidor, para que os problemas possam ser corrigidos.

Leia o sub-tópico ../ApacheEmLinuxFtp depois de acabar o sub-tópico ../InstalaçãoBásica que tratamos aqui.

Descarregar o MoinMoin

Para descarregar o arquivo de distribuição, visite a área de ficheiros a descarregar e obtenha o arquivo mais recente.

O passo seguinte será extrair os ficheiros do arquivo de distribuição (o que já fez, se estiver a ler este texto a partir do seu disco rígido). Se está a ler o texto na Web, a distribuição contém uma versão do arquivo .tar.gz, que pode extrair como mostramos em baixo.

• Em Windows

  • Pode utilizar versões recentes de programas como WinZip, WinRar, e WinAce, que lidam com os arquivos do tipo .tar.gz.

  • na linha de comandos, pode utilizar o GNU gzip e GNU tar para Windows.

• Em Linux
  • Pode utilizar o seu gestor de ficheiros favorito -- deve ser capaz de os extrair.

  • Em qualquer shell, pode utilizar o comando tar.

O arquivo de distribuição é sempre extraído para uma directoria chamada moin-<versão>, por exemplo moin-1.6.0.

Eis como extrairia o arquivo (utilizando GNU tar) e como abriria a directoria com os ficheiros do MoinMoin:

> tar xzf moin-1.6.0.tar.gz
> cd moin-1.6.0

Instalar o MoinMoin

Pode instalar o MoinMoin:

• numa directoria de sistema (se tiver as permissões necessárias para o fazer -- em Linux necessita de ser root)

• numa directoria específica, como a sua directoria home (Linux) ou C:\moin (Windows).

A instalação numa directoria de sistema é mais fácil, por isso, escolha-a se for possível.

Se tiver várias versões de Python instaladas, por favor, utilize a mesma versão para instalar e correr o wiki. Normalmente, com a versão de Pyhton mais recente irá obter os melhores resultados.

Comando de instalação recomendado para Linux (e MacOs X)

Desta vez, como escolheu não utilizar um pacote pré-configurado para o seus sistema, é altamente recomendado que não instale o MoinMoin na directoria por omissão. Isto porque se o fizer e quiser instalar um pacote do moin da sua distribuição, este irá sobrepor a sua instalação existente. O caminho mais frequente para as suas instalações está localizada abaixo de /usr/local (a isto se chama PREFIX). Um comando que deve ser aceite pela maioria das distribuições de Linux e MacOS X é

> python setup.py install --prefix='/usr/local' --record=install.log

Este comando irá instalar os ficheiros partilhados na '/usr/local/share/moin' e o código do moin na /usr/local/lib/python2.x/site-packages/MoinMoin/.

Corrigir falhas no processo de instalação

Se tem problemas com o passo da instalação do ficheiro setup.py, tente utilizar o comando:

> python -v setup.py --quiet install --record=install.log

O -v adicional deve dar-lhe mensagens verbose detalhadas para cada passo.

Em Linux, se obtiver um erro como Invalid Python installation: cannot find /usr/lib/Python2.x/config/Makefile, pode não ter o módulo distutils de Python instalado, faz geralmente parte da Python development libarary (python-dev). Algumas distribuições de Linux podem não o ter instalado por omissão. Por exemplo, em Mandrake é necessário instalar o pacote python-devel, em Debian chama-se python-dev.

Instalar na directoria de sistema por omissão

> python setup.py --quiet install --record=install.log

Este comando instala o MoinMoin na directoria de sistema por omissão (por exemplo em Linux, instala-se normalmente na directoria de Python, na /usr/lib/python2.x/site-packages/MoinMoin e /usr/share/moin). Veja o ficheiro install.log para ver o que foi instalado e onde.

Instalar na directoria home ou outra directoria específica

Exemplo de Linux, instalação na directoria home:

> python setup.py --quiet install --prefix=$HOME --record=install.log

Exemplo de Windows, instalação na directoria C:\moin:

> python setup.py --quiet install --prefix="C:\moin" --record=install.log

Todos os ficheiros MoinMoin serão instalados nessas directorias. Veja o ficheiro install.log para saber quais os ficheiros instalados e onde.

Nota: Provavelmente verá o seguinte aviso:

• warning: install: modules installed to 'C:\moin\', which
  is not in Python's module search path (sys.path) -- you'll
  have to change the search path yourself

Isto significa exactamente o que está escrito. É necessário adicionar a sua directoria install ao caminho da pesquisa do Python, ou o código MoinMoin não será encontrado.

Por exemplo, se está a utilizar um servidor web e um CGI standard, edite o moin.cgi e adicione a sua directoria de instalação ao caminho de Python, assim:

import sys
sys.path.insert(0, 'C:/moin')

Testar a instalação

Como passo final, se tiver acesso à shell ou à linha de comandos, pode verificar se tudo está correctamente instalado e pronto a funcionar. Inicie o Python e digite import MoinMoin. Não deve existir resposta a este comando. Exemplo:

> python
Python 2.4.3 (...)
Para mais informações, digite "help", "copyright", "credits" ou "license".
>>> import MoinMoin
>>>

Se obtiver como resultado:

>>> import MoinMoin
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
ImportError: No module named MoinMoin
>>>

terá de afinar a sua instalação. Experimente modificar o sys.path, como descrevemos em cima.

O que foi instalado

Agora, tem uma instalação do MoinMoin pronta a funcionar. Parabéns! Antes de a configurar, dê uma olhada aos vários ficheiros e directorias que foram instalados.

É importante que compreenda as várias directorias utilizadas numa instalação do MoinMoin, por isso, leia isto com atenção.

Nas descrições seguintes, o PREFIX é o que utilizou com o comando setup.py, ou uma directoria por omissão se não tiver utilizado a opção --prefix. (os valores por omissão habituais em Linux são /usr e /usr/local.) O X.Y é a versão do Python. Normalmente, é 2.3, 2.4 ou 2.5.

Veja o install.log para descobrir mais sobre as seguintes directorias importantes:

• directoria MoinMoin, normalmente PREFIX/lib/pythonX.Y/site-packages/MoinMoin -- é o local onde o código-fonte do MoinMoin se encontra

• directoria share, normalmente PREFIX/share/moin - é o local onde os modelos se encontram

  • directoria data (páginas de wiki, utilizadores, etc.) - deve ser acedida apenas pelo MoinMoin

  • directoria underlay (páginas de wiki) - deve ser acedida apenas pelo MoinMoin

  • directoria htdocs com os ficheiro de suporte de html (imagens para os vários temas, etc.) - o servidor web vai precisar de aceder a essa directoria

  • server - ficheiros-exemplo do iniciar do MoinMoin (como moin.cgi para CGI, e outros ficheiros para outros métodos de iniciar)

  • config - ficheiros-exemplo de configuração do MoinMoin (como wikiconfig.py)

• directoria bin com alguns scripts que o ajudam a utilizar os comandos shell do MoinMoin

Referimos os modelos na directoria share porque normalmente não utiliza esses ficheiros nessa directoria: copia-os para onde é necessário. Desta forma, pode instalar vários wikis sem problemas e actualizá-los facilmente com versões novas do MoinMoin.

Depois de descarregar e instalar o MoinMoin, irá querer "ter um wiki". Como explicamos no final da ../InstalaçãoBásica, tem de copiar várias directorias e ficheiros. Assim, poderá ter os wikis que quiser, e poderá actualizar o MoinMoin facilmente: apenas os ficheiros originais serão sobrepostos, as suas cópias não.

Sempre que copiar esses ficheiros (e modificar a configuração do seu servidor de acordo), está a criar uma instância do wiki. Cada instância do wiki é independente das outras, com uma configuração diferente, páginas diferentes, utilizadores diferente, etc.

Alguns dos passos que tem de executar dependem do servidor web e do sistema operativo utilizado. São descritos em páginas específicas, que deve ler (pelo menos o início) antes de ler esta página. Existem outros passos comuns a todos os servidores web e sistemas operativos (copiar ficheiros, definir permissões), que são descritos aqui.

Os utilizadores de Linux podem utilizar createinstance.sh (um script que cria a instância) em vez de executar todos os passos manualmente:

1. Se não for claro, leia as secções em baixo para mais dicas.
2. Verifique se todas as configurações para a sua instalação estão correctas no script antes de o executar:
   • USER e GROUP devem ser o utilizador e o grupo utilizados pelo seu servidor web para executar o moin.

   • SHARE é o local para onde os ficheiros partilhados são copiados. Veja o install.log do passo setup.py install

3. O script tem um único parâmetro: a sua directoria instance do wiki (veja a secção "Escolher uma directoria" em baixo):

   # ./createinstance.sh /path/to/mywiki

4. Agora avance para a secção "Afinar a configuração"

Leia isto primeiro

Avisos de segurança

Nota para os utilizadores de Windows

Todos os comandos apresentados em baixo são comandos Linux. As descrições de texto que os apresenta devem ser suficientes para o ajudar a perceber o que tem de fazer. Utilize o Explorador do Windows, ou os comandos em modo de texto apropriados.

Escolher um nome de wiki

Escolha um nome único para a nova instância do wiki que pretende criar. Deve ser uma palavra curta, algo que reflicta o tipo de utilização que lhe pretende dar, como o nome da sua empresa, da sua equipa, do projecto em que está a trabalhar, etc.

O nome "mywiki" é utilizado como um exemplo nos diversos comandos apresentados em baixo.

Escolher uma directoria

Escolha uma directoria no seu disco, ela irá conter todos os ficheiros necessários à instância do seu wiki. Inicialmente, a instância do seu wiki utilizará aproximadamente 10MB de espaço em disco. Depois obviamente, irá crescer dependendo da forma de utilização do seu wiki. Um wiki pessoal, mesmo com muitas páginas, poderá vir apenas a ocupar até 30 MB ou 40 MB de espaço em disco. Um wiki concorrido, ou um wiki com muitos ficheiros anexados às páginas, podem utilizar muito mais evidentemente.

Se for o administrador (ou root) do servidor, pode utilizar o que quiser ou o que fizer sentido para si, por exemplo /usr/local/var/moin, /mnt/wikis, etc.

Se for um simples utilizador, provavelmente só será autorizado a editar na sua directoria "home" pessoal. Escolha uma sub-directoria que faça sentido para si, por exemplo a sub-directoria share/moin.

Recolher alguns dados importantes

É aqui que as instruções diferem conforme o servidor web e o sistema operativo utilizado, e dependendo se é o administrador ou um simples utilizador. Veja as páginas apropriadas à combinação do seu servidor web e do seu sistema operativo.

Em Linux, o comando export será utilizado para guardar a informação recolhida. Os utilizadores de Windows devem tomar nota dessa informação cuidadosamente (talvez cortando e colando numa janela do Notepad), ou guardá-la em variáveis de ambiente se utilizarem a linha de comandos.

• PREFIX é o prefixo que utilizou na ../InstalaçãoBásica

• SHARE é o nome da directoria share, como se refere no fim do tópico ../InstalaçãoBásica

• WIKILOCATION é o nome da directoria que irá conter a instância do seu wiki

• INSTANCE é a directoria que contém a instância do wiki. Não pode ser uma directoria existente legível através de Apache, senão não funcionará.

Se for um administrador, ainda será necessário recolher o seguinte:

• USER é o nome do utilizador do servidor web

• GROUP é o nome do grupo ao qual pertence o servidor web

Agora, pessoal de Linux, vamos guardar estas definições na memória:

> export PREFIX=/usr                # isto pode ser outra coisa
> export SHARE=$PREFIX/share/moin   # isto deve estar correcto parra a maioria das pessoas
> export WIKILOCATION=$SHARE        # isto é apenas um exemplo
> export INSTANCE=mywiki            # isto é apenas um exemplo

Os administradores precisarão ainda de mais duas linhas:

> export USER=www-data              # isto é apenas um exemplo
> export GROUP=www-data             # isto é apenas um exemplo

Copiar os ficheiros

Para criar uma nova instância, precisa de criar, em primeiro lugar, uma directoria com o mesmo nome da sua instância, dentro de WIKILOCATION. Depois, é necessário copiar as directorias data e underlay da sua directoria SHARE para a sua directoria instance. Por último, é necessário copiar o ficheiro wikiconfig.py da directoria config para a directoria instance.

O pessoal de Linux apenas necessita de escrever estes comandos:

> cd $WIKILOCATION
> mkdir $INSTANCE                   # cria uma directoria para esta instância
> cp -R $SHARE/data $INSTANCE       # copia a directoria template data
> cp -R $SHARE/underlay $INSTANCE   # copia a directoria underlay data 
> cp $SHARE/config/wikiconfig.py $INSTANCE   # copia o ficheiro exemplo de configuração do wiki

• Repare que é apenas necessária uma directoria underlay no seu sistema se estiver a executar vários wikis (ex. numa farm.)

Definir permissões

Administradores

Os administradores precisam de restringir as permissões dos ficheiros, para que apenas o servidor web (e o administrador obviamente) possa lê-los e editá-los. Para obter segurança máxima, nenhum outro utilizador na máquina deve ser capaz de ler ou escrever na directoria instance do wiki. Não se esqueça que esta directoria contém dados importantes, nomeadamente as senhas (cifradas) dos utilizadores do wiki.

Em Linux, os seguintes comandos devem ser suficientes:

> chown -R $USER.$GROUP $INSTANCE   # verifique se o USER e o GROUP estão correctos
> chmod -R ug+rwX $INSTANCE         # USER.GROUP pode ler e editar
> chmod -R o-rwx $INSTANCE          # todos os outros utilizadores serão rejeitados

Utilizadores normais

Os utilizadores normais, pelo contrário, precisam de alargar as permissões dos ficheiros, para que o servidor web possa lê-los e editá-los. Nas versões mais recentes de Windows, e em algumas versões de Linux e outros sistemas, as listas de controlo de acesso podem ser utilizadas para este efeito. No entanto, elas são poderosas e complicadas, não sendo abrangidas por este documentos. Pergunto a um conhecedor sobre elas.

Sem elas, os utilizadores normais têm de autorizar o acesso a todos para aceder à directoria instance. É a única forma do servidor web lhe aceder e executar o seu trabalho. Claro que isto é MUITO INSEGURO, uma vez que qualquer outro utilizador ou programa do servidor pode ler a directoria. Não deve fazer este tipo de instalação para um wiki aberto ao público.

Em Linux, os seguintes comandos abrem a directoria instance a todos:

> chmod -R a+rwX $INSTANCE

Nota:

• pode também colocar o servidor web e o utilizador normal no mesmo grupo, e abrir a directoria instance apenas aos membros desse grupo. Isto é um pouco mais seguro (dependendo de quem mais se inclui no grupo), mas necessita da cooperação do administrador do servidor; é ele quem define os grupos.

• a outra melhor alternativa seria o administrador do servidor configurar o suexec para executar scripts CGI nas directorias dos utilizadores, sob o id desse utilizador. Desta forma, não é necessário atribuir permissões globais, sendo uma instalação segura, mas também necessita da cooperação do administrador.

Afinar a configuração

Agora, é necessário afinar a configuração do seu servidor web da instância do seu wiki. Procure na página de ajuda apropriada ao seu servidor web, e depois volte aqui para afinar as definições da instância do seu wiki.

Edite o wikiconfig.py. As definições por omissão devem funcionar correctamente na maioria dos casos, mas existem algumas coisas que deve quer alterar, como o nome e logótipo do seu wiki! Leia os comentários do ficheiro wikiconfig.py. Eles irão guiá-lo neste processo.

O tópico AjudaNaConfiguração contém todos os detalhes sobre todas as opções, no caso dos comentários existentes em wikiconfig.py não serem suficientes.

Esta página descreve os passos que tem de dar para criar uma instância do wiki utilizando o MoinMoin em Linux com o servidor web Apache. Já deve ter feito a ../InstalaçãoBásica. As instalações noutros Unices como FreeBSD são muito semelhantes.

Nesta página são discutidos dois cenários de instalação:

1. Tem Permissão de Administrador (é o utilizador 'root' ou pode utilizar sudo) num servidor e pode instalar, modificar ficheiros em praticamente todo lado na máquina, e nomeadamente consegue alterar a configuração Apache.

2. É um Simples Utilizador, que apenas consegue editar ficheiros na sua directoria home, e não consegue alterar o ficheiro de configuração do Apache.

As opções seguintes não são mencionadas aqui:

• utilizar suEXEC

• utilizar FastCGI (ver ../FastCgi)

• utilizar mod_python (ver ../ApacheComModPython)

• configurar um Root Wiki (ver AjudaNaConfiguração/ApacheVoodoo)

• Para mais configurações avançadas e alguns truques, consulte também o tópico AjudasDiversas.

Tabela de Conteúdos

Cenário de Administrador

A directoria exacta das diversas configurações de Apache variam - as directorias utilizadas mais frequentemente são: /etc/httpd/, /etc/apache/ ou /etc/apache2/. Deve ter pelo menos algum conhecimento relativamente à configuração e gestão do Apache, especialmente no que diz respeito a uma configuração num servidor virtual. Se não sabe do que estamos a falar, por favor, leia sobre Ficheiros de configuração e a documentação do Servidor Virtual Apache na documentação sobre Apache.

Em Apache2 é frequente existir uma directoria (como /etc/httpd/conf.d) para servidores virtuais. Assim, todos os ficheiros que tenham a extensão .conf serão incluídos no ficheiro principal de configuração de Apache. Para verificar se isto acontece na sua configuração, pesquise a palavra "Include".

Criar uma instância do wiki

Criar uma instância do wiki implica copiar ficheiros e atribuir permissões apropriadas. Antes de continuar, é necessário saber qual o utilizador e grupo que o seu servidor Apache utiliza. A forma mais simples de o saber, é executar este comando:

> egrep "^User|^Group" /etc/httpd/httpd.conf
User wwwrun
Group nogroup

Isto mostra um resultado frequente: "wwwrun.nogroup". Outros resultados habituais são "nobody.nogroup", "apache.apache" e "www-data.www-data". Claro que pode utilizar o seu. O que importa é que saiba quais os que estão em uso, porque necessitará deles para configurar as permissões de ficheiros.

Uma vez reunida esta informação, leia o tópico ../CriaçãoDeInstânciasDoWiki e siga os passos aí descritos.

Instalar o moin.cgi

Existe ainda um último ficheiro que necessita de copiar, a ponte entre o Apache e o MoinMoin: o script CGI que o Apache irá chamar sempre que uma página do wiki for pedida, e que, por sua vez, invocará todos os componentes do MoinMoin para lidar com o pedido. Na verdade, pode colocar este script onde quiser (todos os caminhos para os ficheiros do MoinMoin precisam de ser configurados para coincidir com a disposição do seu sistema de ficheiros), mas em prol da simplicidade e segurança, sugerimos que siga as instruções que indicamos em baixo, a não ser que pense que sabe fazer melhor.

Vamos criar uma sub-directoria cgi-bin na directoria instance. Utilizando as variáves de ambiente definidas na ../CriaçãoDeInstânciasDoWiki, execute os comandos seguintes:

> cd $WIKILOCATION/$INSTANCE
> mkdir cgi-bin
> cp $SHARE/server/moin.cgi cgi-bin
> chown -R $USER.$GROUP cgi-bin
> chmod -R ug+rx cgi-bin
> chmod -R o-rwx cgi-bin

Configurar o moin.cgi

Quando o moin.cgi é iniciado, importa um módulo do MoinMoin que por sua vez importa outros módulos e o ficheiro de configuração. Os módulos do MoinMoin devem encontrar-se num sistema devidamente configurado (como descrito na ../InstalaçãoBásica), mas é provável que o ficheiro de configuração não seja encontrado. Edite o script do moin.cgi para corrigir esta situação. Adicione estas linhas junto ao topo do ficheiro:

import sys
sys.path.insert(0, '..')

Uma forma ainda melhor seria utilizar um nome de caminho absoluto da directoria que contém o ficheiro wikiconfig.py em vez de '..'.

Configurar o Apache

Agora que todos os ficheiros estão no sítio e devidamente bloqueados (no que toca ao sistema de ficheiros), é necessário configurar o Apache para dar acesso apenas aos ficheiros certos. No entanto, uma vez que a configuração de Apache por omissão varia muito consoante a distribuição que utiliza, e uma vez que os administradores fazem adições e alterações frequentes, não podemos dar instruções exactas que abranjam todos os casos. Em vez disso, descrevemos por alto o que é necessário ser feito e depois damos umas linha específicas que deve adicionar no local apropriado na sua configuração de Apache.

O seu Apache deve ser configurado para que:

• O acesso à sua directoria instance seja negado (as instalações de Apache saudáveis devem, na verdade, negar o acesso a todo o servidor, e depois apenas permitir o acesso a algumas directorias específicas).

• Um Alias seja configurado para redireccionar os pedidos de /moin_static160/ (no URL - veja também a variável de configuração url_prefix_static) para a directoria htdocs (na directoria share como mencionamos no fim da ../InstalaçãoBásica). Tenha em consideração que o url_prefix_static será alterado em cada versão do moin!

• Um ScriptAlias seja configurado para redireccionar os pedidos vindo de onde quiser (sugerimos que utilize o nome da sua instância, por exemplo /mywiki) para o script CGI que acabou de copiar.

Os comandos seguintes irão adicionar duas linhas no final do seu ficheiro de configuração de Apache. Estas linhas apenas abrangem os dois últimos ítens listados em cima. Terá de verificar o primeiro (existe demasiada variação nas distribuições de Linux). Tenha em consideração que talvez tenha de mover as duas linhas para o local apropriado no seu ficheiro config -- talvez para junto de linhas semelhantes.

> echo "" >>/etc/httpd/httpd.conf
> echo "Alias /moin_static160/ \"$SHARE/htdocs/\"" >>/etc/httpd/httpd.conf
> echo "ScriptAlias /mywiki \"$WIKILOCATION/$INSTANCE/cgi-bin/moin.cgi\"" >>/etc/httpd/httpd.conf

Isto deve adicionar duas linhas, como as que apresentamos em baixo, a um ficheiro config (possivelmente deve utilizar um para cada servidor virtual):

Alias /moin_static160/ /usr/local/share/htdocs/
ScriptAlias /mywiki /usr/local/share/moin/mywiki/cgi-bin/moin.cgi

É apenas necessário definir o Alias para o htdocs uma única vez, independentemente do número de wikis que executar com a versão 1.6.0 do moin. É necessário definir um script diferente de alias para cada instância do wiki que tenciona executar. Assim, pode também definir o Alias num ficheiro central de configuração de Apache e definir apenas o ScriptAlias nas configurações de servidores virtuais.

Configurar o MoinMoin

Finalmente, cerifique que o ficheiro wikiconfig.py na directoria instance contém os caminhos correctos para:

• url_prefix_static (coisas estáticas como css/img/js)

• data_dir (a directoria data da instância) e

• data_underlay_dir (a directoria underlay da instância).

Pode utilizar caminhos relativos para as directorias, mas tenha em consideração que são relativos para o script CGI, não para o ficheiro de configuração! É melhor utilizar caminhos absolutos, e prevenir algumas dores de cabeça.

Eis as definições que deve ter no ficheiro config se tiver seguido todas as nossas sugestões:

    data_dir = '../data/'  # é melhor utilizar um caminho absoluto
    data_underlay_dir = '../underlay/'  # é melhor utilizar um caminho absoluto
    url_prefix_static = '/moin_static160' # depende da versão do moin

Existem ainda outras configurações que deve alterar. Para mais informações sobre essas configurações, leia o final do tópico ../CriaçãoDeInstânciasDoWiki.

Testar o wiki

Agora, tudo deve funcionar correctamente. É a altura de reiniciar o servidor Apache (normalmente com "/etc/init.d/apache restart", outras com "apachectl restart") e executar os seguintes passos:

• Execute o MoinMoin CGI Diagnosis: ligue ao "http://127.0.0.1/mywiki?action=test" (ou ao nome e porto que tiver definido no ficheiro de configuração do Apache). Verifique se a informação está correcta. Verifique se as directorias listadas sob Checking directories... estão OK.

• Aceda ao seu novo wiki com o URL "http://127.0.0.1/mywiki/" (ou com o nome e porto que tiver definido no ficheiro de configuração do Apache). Deve ver páginas do wiki -- leia-as.

• Depois avance para a PáginaDeTestesWiki.

• Tente editá-la e guarde as suas alterações.

• Se funcionar, verifique se a sua edição surge na página AlteraçõesRecentes.

• Se surgir, parabéns, o seu novo wiki funciona!

Se algo correr mal, espreite o tópico de Resolução de Problemas, no fim desta página.

Cenário de Simples Utilizador

Por norma, em máquinas partilhadas por muitas pessoas, os simples utilizadores não têm acesso à conta do root, não podem modificar o ficheiro httpd.conf e não podem copiar ficheiros para as directorias de sistema cgi-bin e htdocs. Neste caso, o Apache pode ser configurado de forma a que cada utilizador possa ter um sítio web na directoria home da sua conta shell, utilizando a directiva UserDir. Se o administrador da máquina decidir utilizá-la, todos os URL que comecem com "/~nome-de-utilizador" serão redireccionados para uma das directorias home dos utilizadores, onde têm permissões de escrita e onde podem instalar o MoinMoin.

Como exemplo, vamos considerar o caso de um utilizador chamado "mm". Claro que sempre que vir "mm" em baixo, deve substituí-lo pelo seu nome de utilizador.

Certificar-se de que /~nome-de-utilizador funciona

A instalação na directoria home só funcionará se o administrador (root) a permitir. Assim, o primeiro passo é verificar se funciona. Normalmente, o Apache é configurado de modo que a sub-directoria public_html da directoria home seja utilizada como root do sítio web. Por isso, deve verificar se essa directoria existe.

> ls -ld ~/public_html
drwxr-xr-x   2 mm       users        4096 Nov 30 00:29 public_html

Se a directoria não existir, crie-a, e certifique-se de que pode ser lida e acedida pelo servidor web.

> mkdir public_html
> chmod a+rx public_html
> ls -ld ~/public_html
drwxr-xr-x   2 mm       users        4096 Nov 30 00:35 public_html

Agora, verifique se o URL "/~mm" funciona:

> lynx -error_file=/dev/stderr -dump http://localhost/~mm/ >/dev/null
URL=http://localhost/~mm/ (GET)
STATUS=HTTP/1.1 200 OK

Se obtiver um código de resposta "200 OK", funciona e pode passar para a próxima verificação. Se obtiver uma resposta "403 Forbidden" ou "404 Not Found", há talvez algo de errado com a sua directoria, ou não foi tudo activado pelo administrador.

• Verifique as permissões para a sua directoria home (~) e para a sua directoria public_html. A primeira deve terminar pelo menos com "--x", e a segunda, como apresentámos em cima, com "r-x".

• É também possível que o administrador tenha atribuído outro nome à directoria do sítio web pessoal. O "public_html" é apenas o nome por omissão, mas qualquer um pode ser utilizado. Não há forma de o saber, terá de perguntar ao administrador (root).

• Por último, se a funcionalidade de sítio web pessoal estiver desactivada, pode pedir ao administrador para a activar?

Uma vez feita a verificação se pode ler os ficheiro na directoria, é necessário verificar se pode executar scripts CGI nessa directoria. Utilize os seguintes comandos para criar um script CGI simples na directoria apropriada:

> mkdir -p ~/public_html/cgi-bin
> cat > ~/public_html/cgi-bin/test.cgi
#!/bin/sh
echo Content-Type: text/plain
echo
echo "CGI scripts work"
<CTRL-D>
> chmod a+rx ~/public_html/cgi-bin/test.cgi
> lynx -dump http://localhost/~jh/cgi-bin/test.cgi
CGI scripts work

Se obtiver outro resultado diferente de "CGI scripts work", algo correu mal. Verifique as permissões da directoria como em cima, tente outros nomes (ou pergunte sobre eles). A triste verdade pode ser a que não tem permissão para executar scripts CGI. Terá de pedir ao administrador (root) para este lhe conceder essa permissão.

Uma vez obtida, pode configurar a sua instância do wiki na directoria public_html.

Criar uma instância do wiki

Para criar uma instância do wiki é necessário copiar ficheiros e atribuir as permissões apropriadas. Leia o tópico ../CriaçãoDeInstânciasDoWiki e siga os passos aí descritos.

Instalar os ficheiros htdocs

O servidor web necessita de aceder a estes ficheiros, por isso é necessário copiá-los para a directoria "public_html". Basta utilizar isto:

> cd ~/public_html
> cp -R ~/share/moin/htdocs moin_static160
> chmod -R a+rX moin_static160

Instalar o moin.cgi

Existe ainda um último ficheiro que necessita de copiar, a ponte entre o Apache e o MoinMoin: o script CGI que o Apache irá chamar sempre que uma página do wiki for pedida, e que, por sua vez, invocará todos os componentes do MoinMoin pata lidar com o pedido. É necessário colocar este ficheiro na directoria na qual a execução de scripts CGI está activada. Por omissão, isto deve funcionar:

> cd ~/public_html
> mkdir cgi-bin
> cp $SHARE/server/moin.cgi cgi-bin
> chmod -R a+rx cgi-bin

Configurar o moin.cgi

Quando o moin.cgi é iniciado, importa um módulo do MoinMoin (que por sua vez importa outros módulos e o ficheiro de configuração). Uma vez que foi tudo instalado na sua directoria home, é provável que nada disto seja encontrado. Edite o script do moin.cgi para corrigir esta situação. Adicione estas linhas junto ao topo do ficheiro:

import sys
sys.path.insert(0, '/home/mm/lib/python2.4')
sys.path.insert(0, '/home/mm/lib/python2.4/site-packages')
sys.path.insert(0, '/home/mm/share/moin/mywiki')

Claro que é necessário adaptar os caminhos à sua situação. As duas primeiras linhas devem ajudar a localizar os módulos do MoinMoin, a última deve ajudar a localizar o ficheiro wikiconfig.py.

Nota: Talvez seja necessário editar a primeira linha do ficheiro, para apontar para a versão correcta do Python. O valor por omissão deve ser suficiente, mas uma linha como "#! /usr/bin/python2.4" pode ajudá-lo se o valor por omissão não funcionar.

Nota 2: Neste ficheiro existe uma linha onde se lê request = RequestCGI(). Se tiver um mod_rewrite complexo, adicione properties = {'script_name': '/mywiki'}  nos parênteses. Isto irá permitir ao MoinMoin gerar URLs que comecem por /mywiki e não o caminho que o servidor web passou ao MoinMoin:

def handle_request(req, env, form):
    request = RequestCGI(req, env, form, properties = {'script_name': '/mywiki'})
    request.run()

Configurar o MoinMoin

Por último, verifique se o ficheiro wikiconfig.py na directoria instance contém os caminhos correctos para url_prefix_static (a directoria htdocs), data_dir (a directoria data da instância) e data_underlay_dir (a directoria underlay da instância). Pode utilizar caminhos relativos para as directorias, mas tenha em consideração que são relativos para o script CGI, não para o ficheiro de configuração! É melhor utilizar caminhos absolutos, e prevenir algumas dores de cabeça:

    data_dir = '/home/mm/share/moin/mywiki/data/'
    data_underlay_dir = '/home/mm/share/moin/mywiki/underlay/'
    url_prefix = '/~mm/moin_static160'

Testar o wiki

Agora, tudo deve funcionar correctamente. É a altura de executar os seguintes passos:

• Execute o MoinMoin CGI Diagnosis: > lynx -dump http://localhost/~mm/cgi-bin/moin.cgi?action=test

• Se funcionou, tente aceder ao seu novo wiki com o URL "http://127.0.0.1/~mm/cgi-bin/moin.cgi". Deve ver páginas do wiki -- leia-as.

• Depois avance para a PáginaDeTestesWiki.

• Tente editá-la e guarde as suas alterações.

• Se funcionar, verifique se a sua edição surge na página AlteraçõesRecentes.

• Se surgir, parabéns, o seu novo wiki funciona!

Se algo correr mal, espreite o tópico de Resolução de Problemas, em baixo.

Resolução de Problemas

Veja também o tópico ../ResoluçãoDeProblemas para coisas mais genéricas.

The first thing to do when your wiki does not work as expected is to issue the command "tail /var/log/httpd/error_log" to display the most recent errors. Usually, you will get a hint on what went wrong, like missing file system permissions.

Adicionar permissões para abranger a directoria htdocs

Em algumas (boas) distribuições de Linux (como SuSE 9.0), a opção de acesso a outras directorias que não a document-root "/srv/www/htdocs" com Apache encontra-se desligada por omissão por razões de segurança no "/etc/httpd/httpd.conf" ("/etc/apache2/httpd.conf" no Apache2):

# por ommissão, o acesso é negado a todo o sistema de ficheiros
<Directory />
  Options None
  AllowOverride None
  Order deny,allow
  Deny from all
</Directory>

Para permitir ao Apache o acesso a directorias dora do document root, terá de adicionar estas linhas ao "/etc/httpd/httpd.conf" (no SuSE, recomenda-se que crie um novo "http.conf.local" e que inclua este ficheiro no "/etc/sysconfig/apache2"):

Alias /wiki/ "/usr/share/moin/htdocs/"
<Directory "/usr/share/moin/htdocs/">
   Order deny,allow
   Allow from all
</Directory>
ScriptAlias /mywiki "/usr/share/moin/mywiki/cgi-bin/moin.cgi"
<Directory "/usr/share/moin/mywiki/cgi-bin">
   Order deny,allow
   Allow from all
</Directory>

Claro que necessita de adaptar os caminhos à sua situação particular.

Utilizar o MoinMoin com o Twisted

O Twisted é uma framework de trabalho em rede orientada a eventos para vários tipos de aplicações. Para o MoinMoin, o Twisted é utilizado como um servidro web que importa persistentemente o MoinMoin. Isto tem a vantagem que o interpretador de Python e todos os scripts de Python (incluindo o próprio Twisted e o MoinMoin) só é carregado e iniciado uma vez, e os dados são guardado em memória cache de pedido a pedido, melhorando o desempenho do MoinMoin.

• Primeiro faça uma ../InstalaçãoBásica e uma ../CriaçãoDeInstânciasDoWiki.

Para além da instalação geral, vai necessitar de 3 ficheiros:

1. o script /path/to/cgi-dir/mointwisted (ver tópico "Iniciar o servidor" em baixo)

2. o ficheiro do script do servidor web como mointwisted.py (que necessita de estar na mesma directoria que a sua directoria working).

3. o ficheiro de configuração como /path/to/wikiconfig-dir/wikiconfig.py

Instalar o Twisted

Primeiro, instale o Twisted (ver URL em baixo). Muitas distribuições de Linux têm pacotes do Twisted. Para mais informações sobre a instalação, consulte a documentação do Twisted.

Configurar o servidor Twisted

Copie o ficheiro wiki/server/mointwisted.py para a sua directoria do wiki. Edite e adapte as definições às suas necessidades.

Configuração do caminho de sistema

Se efectuou a instalação standard e não é um programador, salte esta secção. Caso contrário, adicione o caminho para o moin e para o ficheiro config, assim:

sys.path.insert(0, '/path/to/moin')
sys.path.insert(0, '/path/to/wikiconfig')

Opções de classe config

Se efectuou uma instalação standard, as opções por omissão são suficientes. Verifique e altere o que quiser:

Configurar o wikiconfig.py

O ficheiro config de exemplo deve ser suficiente.

Não altere o url_prefix_static uma vez que o valor por omissão se encontra codificado no servidor Twisted.

Iniciar o servidor

em Unix

Em GNU/Linux, Mac OS X ou outro sistema operativo do tipo POSIX, copie o wiki/server/mointwisted para a sua directoria wiki. Adapte o PYTHONPATH e o caminho para twistd.

Inicie o servidor com o ./mointwisted start e teste o seu wiki em http://localhost:8080/. Pare o servidor com o ./mointwisted stop.

Para mais opções, execute o ./mointwisted sem argumentos.

Se quiser iniciar o servidor através de initscript certifique-se que o mointwisted encontra o montwisted.py no arranque!

em Windows

Copie o wiki/server/mointwisted.cmd para a sua directoria wiki. Altere o caminho para apontar para a directoria python-scripts.

Clique duas vezes em mointwisted.cmd para iniciar o servidor. Isto irá criar um nova janela do terminal. Para parar o servidor, feche a janela do terminal.

Como lidar com os erros comuns

Em primeiro lugar siga as instruções

O moin fornece as instruções para a utilização comum. Tente criar um wiki utilizando os valores por omissão das instruções. O seu wiki deve ser então guardado onde o seu está, e deve chamar-se mywiki ... mas pode alterar esse local, e este nome, DEPOIS de o wiki estar a funcionar. Os valores por omissão foram escolhidos cuidadosamente para funcionar para a maioria das pessoas na maior parte das plataformas, ou pelo menos ser um bom ponto de partida.

• Em primeiro lugar, siga as instruções
• Não altere nenhuma configuração a não ser que tenha mesmo de ser.
• Trabalhe com um wiki que funciona antes de o tentar personalizar.

Altere uma coisa de cada vez

Quando o seu wiki estiver a funcionar, personalize-o e adapte-o às suas necessidades, mas lembre-se de alterar apenas uma coisa de cada vez. Provavelmente não percebe como funcionam todas as opções completamente, e se estragar algumas coisas no mesmo passo, será mais difícil corrigi-las

Verifique se o ser servidor web pode utilizar Python

Isto encontra-se também em AjudaNaInstalação/InstalaçãoBásica. Utilize este script:

echo Content-Type: text/plain
echo
echo "Your web server is running as:"
id
echo "CGI scripts work"
echo "Now we try to invoke Python interpreters and get their versions:"
python -V 2>&1
python2.3 -V 2>&1
python2.4 -V 2>&1
python2.5 -V 2>&1
echo "Finished."

para ver se obtém a resposta de que o cgi funciona. Aí, saberá também quais as versões de python utilizáveis. Isto é especialmente útil para utilizadores sem acesso ao root.

Teste Built-in

Existe um modo de diagnóstico built-in útil ao fazer uma instalação; basta juntar "?action=test" ao URL do seu wiki:

lynx --dump http://`hostname`/mywiki?action=test

Se vir um erro de importação aqui, mas

python -c "import MoinMoin"

funciona, é provavelmente resultado de um permissões de ficheiro em falta ou uma definição incorrecta de PYTHONPATH no ambiente do servidor web.

Duelo de Pythons

O problema mais comum que pode encontrar é quando tem uma versão antiga de Python instalada no "/usr", e uma versão de distribuição de Python mais recente no "/usr/local"; isto é frequente nas distribuições de GNU/Linux, que ainda trazem uma versão antiga de Python.

Nesse caso, se escrever "python" na sua linha de comandos, obterá o interpretador de Python mais recente, porque o "/usr/local/bin" está no seu PATH. A situação é outra no ambiente do seu servidor web, e talvez tenha de alterar o caminho do "moin.cgi", assim:

"""
    MoinMoin - CGI Driver Script
...
"""

• Ao instalar, certifique-se que instala o moin com a versão de Python com que quer executá-lo. O python setup.py install irá instalar com o primeiro python no caminho, que pode ser ou não a versão que espera! O /usr/local/bin/python2.4 irá instalar num python específico. Terá de utilizar o mesmo caminho no script do servidor do moin.

Permissões de ficheiro em falta

Se não for o root, os ficheiros instalados podem ser legíveis apenas pelo root, mas eles também precisam de ser legíveis pelo servidor web antes do wiki funcionar. Isto inclui os módulos Python e o próprio sítio. O servidor do wiki necessita também de permissões de escrita na directoria data. Para corrigir esta situação, é necessário descobrir onde está a directoria do módulo do Python; procure-a no install.log, ou execute o comando:

python -c "import sys; print '%s/lib/python%s/site-packages' % ( sys.prefix, sys.version[:3] )"

Para o exemplo em baixo, assumimos que a directoria do módulo do Python é /usr/local/lib/python2.3/site-packages. Torne os ficheiro legíveis a todos utilizando os seguintes comandos:

cd /usr/local
chmod -R a+rX lib/python2.3/site-packages/MoinMoin

Defina as suas variáveis cuidadosamente

Tenha especial atenção se re-escrever em ver de cortar e colar. Os erros de citação no wikiconfig.py podem levar a que as coisas falhem. Os itens seguintes são também problemas com variáveis. Algumas funcionalidades funcionam apenas se forem activadas no wikiconfig.py ou farmconfig.py.

O moin.cgi foi encontrado, mas o Moin não funciona

Se tiver de adicionar a directoria do código do moin no caminho de sistema, especifique o local acima do próprio MoinMoin, para que a palavra MoinMoin seja reconhecida durante o pedido de importação.

Os ficheiros CSS não funcionam

Um erro muito comum é a falta de estilo CSS. O seu wiki parece feio e desinteressante, ao contrário deste belo wiki. Na maioria dos casos, estragou a configuração ao não ter lido as instruções, ou ao tentar personalizar as instruções, por ser mais esperto que nós.

A correcção é muito simples: certifique-se que o seu Alias de Apache e o ScriptAlias NÃO são iguais. Esta configuração de Apache nunca funcionará:

Alias /wiki/ "/prefix/share/moin/htdocs/"
ScriptAlias /wiki/ "/var/www/wiki/moin.cgi"

O Alias é utilizado para fornecer ficheiros estáticos: css, imagens etc. O ScriptAlias é utilizado para esconder o moin.cgi do URL. Tem de utilizar valores diferentes! Pode utilizar o que quiser como ScriptAlias, ou como Alias, mas o Alias tem de corresponder à opção de configuração do url_prefix_static. Eis um exemplo que funciona (o valor por omissão):

# Apache config
Alias /moin_static160/ "/prefix/share/moin/htdocs/"

# Wiki config
    url_prefix_static = '/moin_static160'