Em ambientes onde o GeoServer é executado dentro de um contêiner Apache Tomcat, pode surgir a necessidade de alterar o caminho de contexto (contextPath) da aplicação, ou seja, o endereço pelo qual o serviço será acessado.

Essa modificação é comum em cenários de ambientes compartilhados, integrações com outros sistemas, migrações de infraestrutura ou simplesmente para padronizar URLs (por exemplo, mudar de /geoserver para /geoserver-admin ou /gis).

No entanto, antes de fazer essa alteração, é importante revisar as configurações do Tomcat, especialmente no arquivo server.xml, e entender a diferença entre deploy automático e manual, garantindo que o GeoServer seja publicado corretamente no novo contexto.

Gostaria de agradecer ao Carlos Eduardo Mota, que foi quem elaborou esse tutorial e enviou gentilmente para publicação neste Blog.

1) Verificando o server.xml

Local do arquivo:

$CATALINA_HOME/conf/server.xml

No arquivo, observe:

  • Na tag <Engine>:
    • Propriedade name (geralmente Catalina).
    • Propriedade defaultHost.
  • Na tag <Host>:
    • Propriedade appBase (pasta onde os apps são implantados, normalmente webapps).
    • Propriedade autoDeploy (deve estar true para deploy automático).

Exemplo:

<Engine name="Catalina" defaultHost="localhost">

    <!-- Configurações de cluster, log e segurança omitidas -->

    <Realm className="org.apache.catalina.realm.LockOutRealm">
        <Realm className="org.apache.catalina.realm.UserDatabaseRealm"
               resourceName="UserDatabase"/>
    </Realm>

    <Host name="localhost" appBase="webapps"
          unpackWARs="true" autoDeploy="true">

        <Valve className="org.apache.catalina.valves.AccessLogValve" directory="logs"
               prefix="localhost_access_log" suffix=".txt"
               pattern="%h %l %u %t &quot;%r&quot; %s %b"/>
    </Host>
</Engine>

2) Deploy automático vs. manual

Por padrão, o GeoServer é implantado automaticamente quando o arquivo .war é colocado na pasta definida como appBase no <Host>, geralmente:

$CATALINA_HOME/webapps

Exemplo: colocar meu-app.war em webapps/ fará com que ele seja acessível via /meu-app.

Se você não deseja deploy automático (ou precisa de um contexto customizado), defina o contexto manualmente usando um arquivo de contexto.

3) Deploy manual com arquivo de contexto

  1. Posicione o .war (ou o diretório do app já expandido) fora da pasta appBase.
  2. Crie um arquivo de contexto .xml com o nome que deseja usar como contextPath do app.

Onde criar:

$CATALINA_HOME/conf/[EngineName]/[HostName]/

Exemplo de caminho real:

$CATALINA_HOME/conf/Catalina/localhost/geoserver-admin.xml

Conteúdo do arquivo de contexto:

<Context docBase="webapps.dist/geoserver" />

Neste exemplo, o contexto será:

http://localhost:8080/geoserver-admin

E o diretório do GeoServer está em:

$CATALINA_HOME/webapps.dist/geoserver

O diretório webapps.dist é fornecido nas imagens de container para colocar webapps para distribuição, e não para deploy automático. É provável que nas instalações clássicas do tomcat não deva existir esse diretório. Nesse caso, é necessário criar esse diretório dentro de $CATALINA_HOME.

Observação importante: o nome do arquivo (geoserver-admin.xml) define o nome do contexto (/geoserver-admin) e tem precedência sobre qualquer META-INF/context.xml incluído no .war ou na aplicação.

O arquivo context.xml pode ser expandido e ser utilizado para outras finalidades, como predefinir recursos de conexão de banco de dados (os famosos JNDI), mas isso é assunto para outro post.

Referências