How to host a privately owned documentation with ReadTheDocs or Sphinx - python-sphinx

I am totally new to this thing. Spent a whole day trying to figure out the "most commonly used" approach. What I want to implement is something like readthedocs.org, but for a private customer (and proprietary project).
Almost all of the FAQs, blog posts, howtos, etc, are describing how to host (publish) documentation either with GitHub pages, either with readthedocs.org (.com)
I've tried to use Sphinx (NB: NOT a "Sphinx Search") locally, and I could quite easily build a sample demo docs, but I don't exactly understand how to host a "searchable" solution, like the one it works on http://www.sphinx-doc.org (seems like it uses readthedocs.org as a search backend, though).
I've tried to deploy readthedocs.org locally, but:
The "search" doesn't work (nobody listens on 127.0.0.1:9200).
I was unable to build any documentation (Version not found or
Project not found).
I was unable to add project from my private repository (ssh:)
(NB: I was trying it on Windows, and that might explain items 1-2, but not 3, I believe.)
So far it feels like I've run out of ideas..
Any advice will be highly appreciated !

The only thing you need to host sphinx documentation is a static file server (the search works without a back end, see my answer here.
That said, using a private readthedocs server is probably over-engineering.
Just deploy the files to a static file server and point the base URL (e.g. docs.myapp.com) to the index.html file.
You can automate the deployment with git hooks.
For the sake of completeness: I am sure it is possible to get a local readthedocs server to build your project. But readthedocs is explicitly not designed for On Premise deployments and you might find it hard to get professional support. I was involved in a scenario where the Dev Ops team decided it's way easier to automate the deployment using their usual set of tools after we struggled with build/performance issues of our local readthedocs instance.

If you want to host static documentation you can do this by setting up a static file server like nginx.
Just this file in /etc/nginx/sites-available/default:
server {
listen 80 default_server;
index index.html index.htm index.nginx-debian.html;
server_name _;
location /doc/your-docs {
root /path/to/docs;
}
}
We built a simple tool around this concept to selfhost documentation for multiple projects and version them:
https://github.com/docat-org/docat

Related

Exposed local m2 artifacts from a servlet

Is there a java library that will help in serving the local m2 artifacts under a specific endpoint servlet?
For example: /maven.
Note: I'm familiar with Artifactory and such, but this is not the setup I am looking for.
It's more like I have a project and I want that project to expose the jars in the machine where that project is running.
Working with files is always tricky, you can easily expose data from other directories which can be used by attacker.
To your question: As khmarbaise wrote I'd also really recommend to use Nexus / Artifactory. But if you just need to expose your local repository "the easy way" and "the safe way", you can use web server like Apache2 or Nginx and serve your artifacts as static files.
Lastly if you really want to go to the "danger zone", it's pretty easy to write a Servlet which returns file in some directory, you would call it for example like this: http://localhost:8080/FileServlet?file=junit/junit/4.12/junit-4.12.jar And then use this rewrite filter: https://www.ocpsoft.org/rewrite/ to change URL for example to: http://localhost:8080/repo/junit/junit/4.12/junit-4.12.jar

Automatically set up new Digital Ocean server for Laravel app

I know that https://forge.laravel.com/auth/register is available for $12/month*, but I'd like to understand how to accomplish the same thing myself.
What I assume is possible (and what I'm looking for): I create a server that has only Ubuntu 18.04.3 installed and nothing else, and I upload a script that installs all the appropriate software and sets up MySQL with the correct passwords, etc (without manual intervention).
I've tried Laradock and had tons of problems with Docker and don't want to do that anymore.
I see that https://cloud.digitalocean.com/droplets/new lets me create a LEMP droplet (Ubuntu, Nginx, MySQL, PHP-FPM) with one click. But it lacks Redis, and its versions are outdated (e.g. PHP 7.2).
I've heard people mention Chef (maybe this?), but that seems to be more complicated than what I'm imagining.
Unfortunately I'm not even sure how to search for what I'm trying to do (or how to tag this question); is this called "server provisioning"? I've been searching phrases like "automatic install script redis mysql server for laravel".
Thanks in advance for pointing me in the right direction.
* I also just found https://getcleaver.com/ and https://runcloud.io/server-management, which each look like Forge + Envoyer (and RunCloud offers a free plan).
It is called server provisioning and Chef would be a good fit for this, check out Ansible too - another thing you could do is setup the server yourself and create an image from that server and then base your new servers out of that image, that way you'll have all your services installed from the start.
This sounds like a job or something like Puppet (or Chef/Ansible), however Laravel Envoy may be another tool to look at if you haven't already for the second part of your problem.
I highly recommend Heroku (or similar service), as this is all done out of the box, and has a ton of other great features that make developing a pipeline a breeze.

Jelastic: how to contribute to Certified App source code?

while setting up a basic 1 x NGINX load-balancer in front of 2 backends, I ended up in what it is clear to me to be a bug: the cron of this Certified App cannot be edited:
As you can see, in this particular App the cron file is owned by root:root and doesn't have the extended attribute (the plus on the right of permissions) necessary for the file to be edited also by the logged in user (nginx in this case).
All other certified apps allow instead the main login user to have crontabs, even though I found the permissions of each file vary a lot.
I've stumbled on https://github.com/jelastic/jem/blob/master/etc/jelastic/export.conf and it seems the file to go for proposing a bugfix, but it's last update if Aug-2016, so I guess Jelastic had closed much of its source code.
How can we contribute to Certified App source code?
indeed it is a bug as cron file of nginx user isn't editable in a balancer template, by design in has to be.
As for exports.conf - this file left for backwards comparability, but no more used.
The problem will be definitely fixed in latest templates, as for existing containers - we would like to apply a patch to fix them, if you provide us more details about hosting service provider you are using - we will help with that.
As for contribution to certified templates, all the images are publicly available on Docker Hub, you can create your own version of template based on existing one if you build a docker image and in your Dockerfile you specify
"from jelastic/nginxbalancer" as a base, then you can do any modifications to the filesystem. Next step will be just to replace existing balancer with your custom one.
Anyway, let's start with fix of existing containers.
Many thanks for finding out the bug!

Running TurboGears2 in Amazon EC2

I would just like to ask if anybody here has run Turbogears2 from an Amazon EC2 instance. I've been looking for a way to do it, but so far searching the Web hasn't given me anything I could use as an example. I did see one here:
http://codersbuffet.blogspot.com/2010/05/announcing-turbpgears-ec2-images.html
Though I think the person used an earlier version of TG in his post.
I thought it would be as simple as changing the host parameter in the development.ini, but that did not work. I've also tried connecting to the instance with the -L option for ssh, but it did not work as well (I did this approach for web2py way back, and it worked).
I'm wondering if I need to configure some file somewhere in the TG2 application. I've also tried searching the TG2 documentation. Either I'm not using the right keywords, or I'm just not getting the right results.
Thanks in advance for any help!
DM
By itself EC2 doesn't provide a platform, you can freely choose a deploy environment from mod_wsgi, circus, gunicorn or whatever your prefer. It's not strictly a TurboGears problem, it can be deployed like any other WSGI application.
There are some tutorial for a step by step deploy on Apache+mod_wsgi and Circus+chausette on the TurboGears documentation, you can find them here: http://turbogears.readthedocs.org/en/latest/cookbook/deploy/index.html
Avoid deploying on gearbox+wsgiref because it is not meant for production usage, if you want to use gearbox I suggest you give a try to waitress

Symfony2 deployment via ftp

I tried to deploy my project with capifony, becouse I found here an answer, that with capifony deployment is easy. Well I don't think it is, so my question is:
How can I deploy my project via ftp, I put all my files on the server but even if I browse to web/app.php, the only thing I get is an empty page, whatever route I write in the url. So someone please explain me how can I get this work! Thank you!
A couple of things to think of when deploying a Symfony2 project to a new server or computer (as far as I've encountered) might be:
Make sure that the server and it's PHP installation meets the Symfony2 requirements (and perhaps also the recommendations)
Check that you've somewhat followed the installation instructions (found here)
Try to clear the cache
Make sure that the web server and it's PHP process have write permissions to the cache folder
If none of these helps, try to modify the app_dev.php to temporarily allow access from your current (client) IP (instead of restraining it to localhost). Then, hopefully, you'll get a more useful and detailed error message, instead of the blank page (which often is caused by some fatal error that have occurred during the initialization of the framework and its kernel)
Update: Noticed now that you've tagged your question with 'windows', but that you don't mention which server you're trying to deploy to. I wrote the above with some *nix based server in mind, but hopefully some of it are applicable to Windows servers too (but there might be other common sources of error running under Windows that I'm not familliar with

Resources