Guia open source para una instalacion prolija

Tutorial paso a paso para instalar, ejecutar y usar la app.

Esta pagina resume el flujo ideal para un buen repositorio open source: instalar Git y Python, clonar el proyecto oficial, preparar el entorno, abrir la aplicacion por primera vez y entender donde quedan guardados los datos.

Ver repositorio Ver video tutorial

Windows con instalacion rapida mediante iniciar_windows.bat
macOS y Linux con comandos manuales claros
Bloques listos para copiar en terminal
Notas sobre ubicacion de datos y primer uso real

Flujo recomendado

Instala dependencias, clona el repo y corre la app local.

La aplicacion corre localmente con Python y Django. En Windows conviene usar el .bat de primer arranque. En macOS y Linux, el camino correcto es hacerlo desde terminal con entorno virtual.

Datos locales db.sqlite3, .env, media y venv

Entrada http://127.0.0.1:8000/admin/

"copiar, pegar, ejecutar y seguir sin perder tiempo"

"una guia pensada para usuarios y tambien para contribuidores"

Windows

Instalacion guiada con Git, Python y primer arranque con iniciar_windows.bat.

macOS

Instalacion por terminal con Homebrew, entorno virtual y comandos listos para copiar.

Linux

Flujo manual para Ubuntu o Debian y referencia para otras distros.

Antes de empezar

Git y Python son la base de una instalacion limpia.

Si tu idea es descargar de forma segura y que no haya alertas raras del navegador o de bloqueadores, el mejor camino es instalar Git y Python primero, clonar el repositorio oficial y ejecutar la aplicacion desde tu propia carpeta local.

Python 3.12 o superior

Es el runtime principal del proyecto. En Windows conviene instalarlo desde python.org marcando Add Python to PATH.

Descargar Python

Git

Permite clonar el repositorio oficial, actualizarlo con orden y contribuir como corresponde en un proyecto open source.

Descargar Git

Carpeta fija

Todo queda guardado dentro de la carpeta del proyecto. Elegi un lugar permanente antes del primer arranque para no mover la base ni el entorno virtual.

Windows

La ruta recomendada para la mayoria de los usuarios.

En Windows el proyecto tiene una ventaja clara: iniciar_windows.bat automatiza el primer arranque. Aun asi, conviene instalar primero Python y Git, clonar el repositorio oficial y ejecutar el .bat como administrador la primera vez.

Instalacion segura

Clonar con Git evita descargas dudosas y deja el origen del proyecto bien claro.

Primer arranque

El .bat crea el entorno, instala dependencias, aplica migraciones y puede crear el acceso directo del escritorio.

Verificar herramientas

Ejecuta estos comandos en PowerShell o CMD para confirmar que Python y Git ya estan instalados.

Comprobar versiones

python --version
git --version

Clonar el repositorio

Entra en una carpeta de trabajo tuya, clona el repo oficial y ubicate dentro del proyecto.

Clonar y entrar

git clone https://github.com/Excel-ente/calculadora-de-costos-de-recetas.git
cd calculadora-de-costos-de-recetas

Primer inicio automatico

La primera vez conviene ejecutar el archivo como administrador. El proceso tambien puede ofrecerte crear un acceso directo al escritorio.

Ejecutar el .bat

.\iniciar_windows.bat

Ruta manual alternativa

Si preferis controlar cada paso, este bloque hace exactamente lo mismo de forma explicita desde consola.

Instalacion manual en Windows

python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt
copy .env.example .env
python manage.py migrate
python manage.py createsuperuser
python manage.py runserver

macOS

Instalacion manual prolija desde Terminal.

En macOS no se usa el archivo iniciar_windows.bat. El camino correcto es instalar Git y Python, clonar el repo y levantar Django manualmente con entorno virtual. Si ya usas Homebrew, el proceso es directo.

Preferencia

Si no tenes Homebrew, podes instalar Git y Python desde sus sitios oficiales y luego seguir los comandos del proyecto.

Comando de activacion

En macOS el entorno virtual se activa con source venv/bin/activate.

Instalar herramientas

Si ya usas Homebrew, este es el camino mas corto para dejar Git y Python listos.

Instalar con Homebrew

brew install python git
python3 --version
git --version

Clonar y preparar el proyecto

Clona el repositorio oficial y entra a la carpeta antes de crear el entorno virtual.

Clonar el repositorio

git clone https://github.com/Excel-ente/calculadora-de-costos-de-recetas.git
cd calculadora-de-costos-de-recetas

Crear entorno y arrancar Django

Este bloque deja el proyecto listo para correr localmente y abrir el panel de administracion.

Primer arranque en macOS

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
python manage.py migrate
python manage.py createsuperuser
python manage.py runserver

Linux

Terminal clara para Ubuntu, Debian y derivadas.

En Linux el flujo es muy parecido al de macOS, pero normalmente primero instalas paquetes del sistema con el gestor de tu distro. Aca te dejo la ruta base para sistemas Debian o Ubuntu. Si usas Fedora, Arch o similares, cambia ese primer bloque por el equivalente de tu distribucion.

Paquetes base

Necesitas Python 3, soporte para entornos virtuales, pip y Git.

Uso diario

Luego del primer arranque solo activas el entorno y levantas runserver cuando quieras usar la app.

Instalar dependencias del sistema

Este ejemplo sirve para Ubuntu y Debian. En otras distribuciones usa el gestor de paquetes equivalente.

Instalar Python y Git

sudo apt update
sudo apt install -y python3 python3-venv python3-pip git

Clonar el proyecto

Clona el repositorio en una carpeta tuya y entra antes de crear el entorno virtual.

Clonar el repositorio

git clone https://github.com/Excel-ente/calculadora-de-costos-de-recetas.git
cd calculadora-de-costos-de-recetas

Entorno virtual y servidor

Con este bloque ya quedas listo para entrar al admin local y probar una receta de ejemplo.

Primer arranque en Linux

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
python manage.py migrate
python manage.py createsuperuser
python manage.py runserver

Donde quedan tus datos

Todo vive dentro de la carpeta del proyecto.

Este punto es importante para usuarios y para soporte. Si mueves la carpeta del proyecto sin entender que guarda adentro, puedes perder la referencia al entorno o a la base local. Por eso conviene elegir una ruta fija desde el inicio.

db.sqlite3

Ahi queda la base de datos local con usuarios, recetas, productos y configuracion del sistema.

.env

Guarda la configuracion principal del entorno local y parametros del proyecto.

media/

Contiene archivos subidos por la aplicacion, como imagenes u otros recursos del negocio.

venv/

Es el entorno virtual de Python. No conviene borrarlo ni moverlo si luego quieres relanzar la app rapido.

Uso diario y comunidad

Despues del primer arranque, usar y mejorar el proyecto es simple.

En Windows puedes relanzar la app con el acceso directo del escritorio o con el mismo archivo iniciar_windows.bat. En macOS y Linux, basta con entrar a la carpeta del proyecto, activar el entorno virtual y ejecutar python manage.py runserver.

Si te sirve la herramienta, tambien puedes abrir issues, proponer mejoras y enviar pull requests. Ese es el tipo de documentacion que fortalece un repositorio open source y ayuda tanto a usuarios finales como a contribuidores.

Probar el sistema con una receta de ejemplo.
Verificar que la base y las imagenes queden en tu carpeta local.
Guardar el acceso directo o tus comandos favoritos para uso diario.
Volver al repositorio para reportar dudas o mejoras.

Consejo practico: si el proyecto te ayudo, deja una estrella en GitHub. Esa senal tambien ayuda a que mas personas encuentren el software y confien en el repositorio.

Abrir GitHub