Add .htaccess sample

[jonasraoni]

Describe the problem you would like to solve
Forum requests usually include petitions related with rewrite rules.
Those petitions sometimes come from expert users that don't know OxS tools.

Describe the solution you'd like
Drupal includes a preconfigured .htaccess in root:
https://github.com/drupal/drupal/blob/9.5.x/.htaccess

A default .htaccess (or an example to let final user enable it) would probably help to reduce forum petitions and will make it easier to enable restfull URLs.
The file start with usual/basic config and grow in future with extra examples to uncomment with common scenarios (subdomain, subfolder, proxy...).

Who is asking for this feature?
System Administrators

p.s.: Posted on behalf of @marcbria.

[marcbria]

A basic .htaccess could be something as:

<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteBase /
    RewriteRule ^api/v1(.*)$ /index.php/api/v1$1 [L,R=307]
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteRule ^(.*)$ /index.php/$1 [QSA,L]
</IfModule>

But it could be extended with well-know tips like:

## Uncomment to enable php error logs and set the folder:
# <IfModule mod_php.c>
#     php_flag log_errors On
#     php_value error_log /var/log/apache2/php-errors.log
# </IfModule>

## Uncomment to ask apache to "Force HTTPS":
# SetEnv HTTPS On
# PassEnv HTTPS
# SetEnvIf X-Forwarded-Proto "^https$" HTTPS=on

## ...

[jonasraoni]

If I'm not mistaken, PKP is generally against using custom URLs due to issues with indexing platforms, there's a reference here citing Google Scholar: https://forum.pkp.sfu.ca/t/restful-urls-on/32688/10
As the post is quite old, I'm not sure if the problem remains (if it remains, it would be great to solve it in another way...).

In general I support such URLs, and I think we could also add a meaningful description to them (e.g. /issue/123/short-description), if that's still a SEO thing 😁

[marcbria]

Wow... I didn't know about this. As I read James:

Google Scholar uses* the existence of "index.php" to identify whether something is OJS.

And this really blows my mind.

So we are forced to maintain urls in a specific way because google (THE megacorporation) is too lazy to (for example) check the "generator" tag in the html code? Are we really?

Honestly, it seems crazy to me and I don't think we should let google dictate the way PKP operates.

I mean, if we (as a group), believe that PKP deserves clean urls, google can't impose their criteria on us, can they?

Besides it's a "requirement" that is far from obvious and (as far as I know) is not documented other than in the post you comment on.

In short, I suggest leaving aside what google says and open the debate on what we think as PKP.

I did a quick survey and I see that most large institutional services use restfull urls, so I think it's good to standardize this and make it easier for smaller services to present themselves to the world in the same way.

Personally I am in favor of clean urls as they are easier to remember and improve SEO in all search engines (that's why it's a common practice in any other CMS).

Thanks for the information Jonas.

[NateWr]

I mean, if we (as a group), believe that PKP deserves clean urls, google can't impose their criteria on us, can they?

Yeah, it's infuriating. I took up the fight with someone from Google Scholar here: #7003. But they quit GitHub in response.

It seems to be something about how GS can only decide what to index at the URL level -- they're not allowed access to Google's full indexing capabilities. My response is that this is Google's problem and we shouldn't bow to it. But Google's response is to walk away and I've been outvoted at PKP.

Frankly, it's embarrassing.

[marcbria]

I did remember a google person leaving a conversation the moment the arguments fell under their own weight... but I had completely forgotten the reason for the #7003 discussion.

Honestly, I think the requirements should be dictated by the community and PKP (always thinking of the collective benefit) and then let google (or whoever) adapt as they want/can. 25K journals it's something that even google could ignore.

I can't imagine the arguments, but if someone thinks we should give in, I think that, at least, a public statement should be issued explaining google's authoritarian attitude and why we acted as we acted.

If you want, I'll take the issue to the TC for discussion and a proposal?

In any case, regardless of what is proposed and finally decided, adding an example htaccess and allowing each service to decide what to do might be a good idea, isn't it?

[NateWr]

On the original question: WordPress generates the .htaccess based on your settings ("permalink" structure). Since we allow things like disable_path_info, we would probably need to do something similar.

[marcbria]

Si os parece bien, en tanto que gitHub autotraduce y me resulta más cómo escribir en mi idioma nativo, os escribo en Español y así probamos que tal funciona? (Si fuese un problema, avisad y vuelvo al inglés).

Que las herramientas de PKP generen el htaccess sería ideal, pero eso supone un tiempo de desarrollo que sospecho que ahora mismo no tenemos.

Os propongo abordar el problema en 3 pasos:

1. Añadir un template de htaccess para que la gente lo active si lo considera necesario.
2. Mejorar dicho template según el feedback que recibamos en el foro (y tomando ideas de otros CMS).
3. Automatizar la creación del htaccess (como hace wordpress), incluso revisando si el mod_rewrite está activo.

Si estamos de acuerdo en el punto 1 puedo hacer un PR para que se incluya en la siguiente release.

[marcbria]

Tal vez se desprende de lo dicho pero olvidé comentar que (como hace Drupal) el htaccess es también una buena oportunidad para añadir mecanismos de protección sobre algunos directorios:

https://forum.pkp.sfu.ca/t/how-to-prevent-direct-access-folder-and-file-through-url/73705

PD: Quede claro que no pretendo con esto trasladar la responsabilidad de los/las administradores/as hacia PKP.
Cada administrador/a es responsable de sus servidores pero un template facilita la comprensión de las peculiaridades de un proyecto.

[jonasraoni]

@marcbria The translation sounds clear for me (with the exception of some words, I can understand the original as well 😁)

I support starting with something small, such as a TEMPLATE.htaccess, and the folder protection sounds like a nice addition for users that have limited server access/are unskilled 🤔

I think it's generally good to add a note stating that it's a not well tested template (or perhaps it is?) and simple instructions (e.g. link to the mod_rewrite documentation + basic troubleshooting: "if something stops working, rename the file back to xxx").

[marcbria]

So I'll continue with my precarious English, which won't be flowery, but I suspect it will leave less lost in translation (btw, great movie). :-)

It's ok if I do a PR and we start talking over an specific proposal, or you prefer to assign the task to somebody?

[NateWr]

The Spanish translation was very clear to me. Stick with that if you feel more comfortable writing in Spanish. 👍

I'll let Alec make the call on this. But I really don't think having a template htaccess file is going to do much on its own. We need to think about this problem as a social problem, not a technical one. Questions that arise are:

• Will our install documentation need to be updated to take this into account? Any other documentation?
• Will our docker install need to be updated?
• Under what circumstances might the template break someone's site? (nginx, incorrect configuration, non-standard subdirectories)

Just providing a template feels like we're not going to solve problems for more than a tiny fraction of our community.

[asmecher]

Hi all! I've been following this from afar. I'd like us to consider the long-term alignment towards Laravel tooling here, and also this proposal for rearranging the app structure: #1832

If we choose to re-architect the app's deployment considerably, including e.g. the index.php wrapper, it'll probably be a good time to draw together our deployment recommendations/options into a clearer recommendation. Right now we have the accumulated legacy of a lot of very old decisions (starting with OJS 2.0).

Any move away from the we-deploy-on-anything flexibility of OJS would need to be considered too. I'd be nervous about shipping a .htaccess that was expected to work; many hosts will not have it configured to work, and there might be an expectation that if the file is present it'll be functioning (and providing some kinds of protection in the process).

[marcbria]

En Discussions no tengo claro cuando continuar un hilo o abrir uno nuevo. Si lo hago mal, avisad.

Respondiendo a Nate:

Will our install documentation need to be updated to take this into account? Any other documentation?

Estoy sugiriendo una aproximación por fases (de un simple template a algo más dinámico), aprehendiendo del feedback que nos vaya llegando en cada momento.

En un inicio el mismo template podría "autodocumentarse", explicando en su cabecera que:

• No es responsabilidad de PKP la administración del servidor y que se ofrece el template como modelo.
• Que se trata de una prueba y que solo funciona en el contexto X (pe: LAMP with mod_rewrite).
• ...

Si el template crece para incorporar más modelos (pe: funcionar tras un proxy, segurizar directorios, etc) o si termina siendo un htaccess autogenerado, entonces creo que si que haría falta documentación... pero todavía veo esto muy lejos.

Will our docker install need to be updated?

Llevamos un tiempo repensando como crear las imágenes docker para que sean más útiles para la comunidad (cubriendo prod, dev y testing) y para que sirvan para todas las herramientas de PKP (OxS).

Uno de los cambios que incorporan las nuevas imágenes (y el detonante de este hilo) es que van a usar htaccess, pues en producción los contenedores suelen encontrarse tras un proxy-reverso y con httpS y un htaccess facilitaría que sean contenedores "plug&play" (la gran ventaja de las imágenes es que nos ofrecen un contexto muy controlado (Debian11, Apache2, MariaDB10, PHP8) así que ahí si se podemos crear reglas "sólidas como una roca").

Así que si, la idea es actualizar las imágenes existentes pero el proyecto docker-ojs sigue con la etiqueta de "Beta", así que nadie se puede quejar todavía por estos cambios. :-)

Under what circumstances might the template break someone's site? (nginx, incorrect configuration, non-standard subdirectories)

Las circunstancias por las que el template podría no funcionar son las que enumeras y seguro que alguna más... pero siempre tendrán que ver con la pericia de la persona que se encargue de la tarea.
Dicho de otro modo: Siempre que alguien modifique un htaccess sin saber lo que hace puede romper un sitio, pero eso es algo que ya está sucediendo.

Me explico:
Tenemos el foro y gitHub llenos de indicaciones para configurar las reglas mod_rewrite (o el equivalente nginx) y hilos eternos llenos de prueba-error en los que (sobre todo Clinton y con infinita paciencia) el equipo de support ayuda a la gente a configurar correctamente su servidor.

Esa necesidad y peticiones no van a desaparecer... al contrario, con el tema de la API las reglas se han complicado un poco más, así que vamos a recibir más peticiones en ese sentido.

En este sentido, un template permite:

1. Garantizar que el modelo de partida es correcto (los usuarios cometemos "herrores" :-P).
2. Garantizar que el modelo va acorde a la versión y herramienta que se configura.
3. Documentar el mismo template explicando cada regla.

Y respondiendo a Alec:

En tanto que el template...
a) no se activaría hasta que alguien lo renombra o edita y...
b) estaría empaquetado con la versión de OxS.

no veo conflicto con ninguno de los elementos que enumeras como problemas potenciales.

[marcbria]

@NateWr Hice un breve comparativa del proceso de instalación de distintos CMS y el patrón emergió rápidamente.

Hay distintos estilos (algunos realmente minimalistas) pero los "asistentes" (aka. wizards) son el más usados.

Aquí te paso el enlace (avisa si quieres derechos de escritura):
https://www.figma.com/file/jhDuBde04eRufrBqEEHkO6/Untitled?node-id=0%3A1

Las etapas de todos los instaladores son (siempre por orden):

1. Decision: Installation or Upgrade?
2. Language selection
3. Welcome, terms and license
4. Check Requirements: System and non system ones.
5. DB credentials: including advanced sections for drives or table_prefix.
6. Web Config: admin credentials, folders, regional settings...
7. Installation: A progress bar...
8. Sucess!!
9. Admin as login

Así pues, se podrían agrupar las secciones de nuestro instalador en base a estos grupos y podríamos incluir lo del htaccess en la sección de check requirements (o mejor web config?) con un colapsable que diga "¿Quieres urls limpias?".

Lo que me parece curioso es que ninguno de los CMS mencionados preguntan respecto al tema del htaccess... lo que hace que me pregunte si no estaremos tomando un camino equivocado.

En el caso de Drupal (no conozco tan bien el resto) se aplica directamente un htaccess genérico.

Un saludo,
m.

[NateWr]

Thanks @marcbria, that's helpful to see the other software. I wizard is definitely the best approach. It's probably beyond us right at this moment, but that figma will provide useful research if/when we can redesign it.

For now, what I was wanting was some draft language regarding the htaccess section. For example, if we check for mod_rewrite and htaccess, what should the install form say if it exists or not? What options should the user have to choose from? Can you write a sample section for htaccess in the install form? (You can write it in Spanish -- we just a basis to begin discussing.)

[marcbria]

Estoy lejos de ser un experto en UI/UX pero podría ser una cosa así:

Y si ojs crea el fichero .htaccess (y modifica el config.inc.php) automáticamente, la sección de "Instrucciones" podría desaparecer.

Pero Nate, estoy siguiendo tus instrucciones con esto para seguir tu proceso mental pero llegados a este punto creo que esto no es una buena idea.

Me explico:

1. Me parece muy sospechoso que ninguno de los CMS que he consultado ofrezcan ayudas para crear reglas de servidor (pero en cambio si ofrecen un htacess de ejemplo o guía)..
2. Creo que tiene mucho sentido que sea así pues se trata de una tarea que requiere conocimientos técnicos pues hay muchas cosas que pueden salir mal cuando aplicas reglas incorrectas (resulta muy complicado hacer un "generador universal", pero si es fácil dar un modelo).
3. Como sysOps un template me si me facilita el trabajo (veo el modelo y entendiendo lo que hago, lo puedo adaptar)... y me resulta mucho más cómodo renombrar y editar un ".htaccess.TEMPLATE" que pasar por el wizard del instalador, hacer cut&paste, etc.

En resumen:

No tengo nada claro que el esfuerzo de implementar todo esto merezca la pena cuando podemos conseguir más o menos lo mismo con un simple fichero de texto... cuando además esto desincentivará a usuarios sin los conocimientos técnicos necesarios.

Por otro lado, mostrar esta opción en el instalador si puede derivar en un incremento de peticiones de soporte que es justo lo contrario de lo que pretendemos.

Con el pertinente disclaimer en la cabecera (al estilo del que he publicado aquí) ¿qué argumentos hay en contra de un .htaccess.TEMPLATE?

[NateWr]

what arguments are there against a .htaccess.TEMPLATE?

From what i said before:

In our experience "self-documenting" solutions do not solve real-world problems because people do not know how to find what they need or understand how to use something. They create as many problems as they solve.

Basically, I don't think it will solve our problem for more than 1-5% of people. And it will add steps to our installation documentation, which is already more complicated than we would like.

[marcbria]

Basically, I don't think it will solve our problem for more than 1-5% of people.

Viendo los mensajes en el foro, un 5% me parece un porcentaje muy bajo.
Si miras algunos posts sobre este tema puedes ver que todos pasan por un "estas son las reglas genéricas" y muchos justo ahí se resuelven.

Yo creo que al menos un 50% de las peticiones que tienen que ver con el mod_rewrite no hubieran existido si ofreciésemos una plantilla y estoy convencido de que en todos los casos (incluso cuando no se hubiese resuelto) el sysadmin de turno hubiese agradecido un modelo en vez de tenerlo que buscar en los foros o en una sección de las FAQs... para descubrir algo más tarde que en la versión 3.x hay que redirigir también las llamadas a la /api.

Esta es una ventaja adicional de la propuesta: el template estaría vinculado a la versión... pues (como decía) estas reglas pueden cambiar con el tiempo.

Aclarar que mi pretensión no es resolver el problema de forma universal (para usuarios no expertos), sino allanar el camino de aquellos que si tienen el conocimiento pero no la información.

And it will add steps to our installation documentation, which is already more complicated than we would like.

Creo que una cosa es independiente de la otra. En tanto que las clean-urls es algo opcional, yo no me sentiría obligado a añadirlo a la documentación de instalación. Pero si quisiésemos, podría ser algo muy simple que remita a la misma documentación del template, estilo:

"Do you want to remove index.php? Read .htaccess.TEMPLATE" (o algo mejor escrito :-P)

In our experience "self-documenting" solutions do not solve real-world problems because people do not know how to find what they need or understand how to use something. They create as many problems as they solve.

No conozco en que escenarios ha sido así, pero si puedo imaginar que ese es un riesgo.
Lo que no creo es que esta propuesta genere tantos problemas como los que resuelve.

Al final, lo que estoy planteando es documentar algo mejor lo que tenemos perdido en las FAQs... y sugiero hacerlo del mismo modo que lo hacen el resto de CMS (pues muchos sysadmins no conocen OJS pero si han instalado antes un WP o un Drupal).

Pero creo que estoy empezando a repetir argumentos y si la propuesta no convence, pues no convence y no pasa nada.

Gracias por tu tiempo Nate.

[marcbria]

The .htaccess.TEMPLATE could be something like this:

######################## DISCLAIMER ##########################
# This template is provided "as is", as a model and without  #
# any guarantee that it will work for your website, nor any  #
# responsibility on the part of PKP.                         #
#                                                            #
# The configuration of a server is a technical task that     #
# your organisation must guarantee. Do not use this template #
# if you have no knowledge of apache2 server administration. #
##############################################################

######################### IMPORTANT ##########################
# This template is for apache2 only and will only work if    #
# your webserver is accepting htaccess files.                #
#
# Do not attempt to use this template with other web servers #
# without first adapting the rules included here.            #
##############################################################


# CLEAN URLS: Rules required for restful urls.
# You must ensure mod_rewrite module is enabled in apache2.
# Once enabled you must go to OxS config.inc.php and set
# the variable "restful_urls" to "On".
# More information: 
# https://docs.pkp.sfu.ca/faq/en/site-administration#how-can-i-remove-indexphp-from-the-urls-in-ojs

<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteBase /
    RewriteRule ^api/v1(.*)$ /index.php/api/v1$1 [L,R=307]
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteRule ^(.*)$ /index.php/$1 [QSA,L]
</IfModule>


## PHP LOG ERRORS: Rules to redirect php's log file.
## Uncomment to enable php error logs and set the destination file.

# <IfModule mod_php.c>
#     php_flag log_errors On
#     php_value error_log /var/log/apache2/php-errors.log
# </IfModule>


## FORCE HTTPS: Rule to force HTTPs 
## Uncomment to make apache2 use httpS.

# SetEnv HTTPS On
# PassEnv HTTPS
# SetEnvIf X-Forwarded-Proto "^https$" HTTPS=on

## PROTECT FOLDERS: Rule to avoid run php in upload folders.
## ...

[jonasraoni]

It's also needed to consider if the user already has a .htaccess file in his server, then before overwriting, it should be backed up.

[marcbria]

Yes. Instructions should ask for $ mv .htaccess.TEMPLATE .htaccess
If file exists, it will generate an error so user could save former .htaccess.

The full proposal assumes we are talking to a "sysadmins", not plain users.

[marcbria]

To illustrate, this is the kind of scenario where I thought a well tested .htaccess would be useful:
https://forum.pkp.sfu.ca/t/restfull-urls-htaccess-404-on-administration-ver-3-3-0-11/73940

At this moment we don't have detailed documentation to refer and we don't know what did this person tried.

But probably you are right Nate and a htaccess template won't really help and the problem is the lack of tech knowledge.